> For the complete documentation index, see [llms.txt](https://docs.senmo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.senmo.io/segment-ledger/errors.md). # Errors The Segment Ledgers API uses conventional HTTP status codes together with a standardized error response format to communicate why a request could not be processed. Every error response includes enough information for your application to determine what went wrong and how to recover from the failure. Errors can occur for many reasons, including authentication failures, missing parameters, validation errors, insufficient permissions, or business rule violations. ## Error Response Format Every unsuccessful request returns a JSON object using the following structure. ```json { "statusCode": 400, "statusMessage": "Validation Error", "error": { "code": "VALIDATION_ERROR", "message": "ledger_id is required" } } ``` ### Response Fields | Field | Type | Description | | --------------- | ------- | ----------------------------------------------------------------- | | `statusCode` | Integer | HTTP status code returned by the API. | | `statusMessage` | String | Human-readable summary of the error. | | `error.code` | String | Machine-readable error identifier used for programmatic handling. | | `error.message` | String | Detailed description of what caused the error. | *** ## Error Categories Errors generally fall into one of the following categories. | Category | Description | | -------------- | ----------------------------------------------------------------------------------- | | Authentication | Missing or invalid API credentials. | | Authorization | The authenticated client does not have permission to access the requested resource. | | Validation | Required parameters are missing or contain invalid values. | | Resource | The requested resource could not be found. | | Business Logic | The request is valid but violates a business rule. | | Conflict | The operation conflicts with the current state of the resource. | | Rate Limiting | Too many requests have been submitted within a short period. | | Server | An unexpected error occurred while processing the request. | *** ## Common Error Codes ### VALIDATION\_ERROR The request contains invalid or missing data. #### Example ```json { "statusCode": 400, "statusMessage": "Validation Error", "error": { "code": "VALIDATION_ERROR", "message": "ledger_id is required." } } ``` Common causes: * Required field is missing * Invalid UUID format * Invalid currency code * Invalid amount * Invalid request body *** ### INVALID\_REQUEST The request cannot be processed because its format is incorrect. #### Example ```json { "statusCode": 400, "statusMessage": "Bad Request", "error": { "code": "INVALID_REQUEST", "message": "Malformed JSON body." } } ``` Possible reasons: * Invalid JSON * Unsupported Content-Type * Incorrect parameter types *** ### UNAUTHORIZED Authentication failed. #### Example ```json { "statusCode": 401, "statusMessage": "Unauthorized", "error": { "code": "UNAUTHORIZED", "message": "Invalid API key." } } ``` Possible reasons: * Missing Authorization header * Invalid API key * Expired API key * Incorrect Bearer token *** ### ACCESS\_DENIED The authenticated client is not allowed to perform the requested operation. ```json { "statusCode": 403, "statusMessage": "Forbidden", "error": { "code": "ACCESS_DENIED", "message": "Access to this ledger is denied." } } ``` Possible reasons: * Ledger ownership mismatch * Missing permissions * Restricted resource *** ### RESOURCE\_NOT\_FOUND The requested resource does not exist. ```json { "statusCode": 404, "statusMessage": "Not Found", "error": { "code": "RESOURCE_NOT_FOUND", "message": "Account not found." } } ``` Examples: * Ledger not found * Account not found * Transaction not found * Statement not found *** ### RESOURCE\_CONFLICT The request conflicts with an existing resource. ```json { "statusCode": 409, "statusMessage": "Conflict", "error": { "code": "RESOURCE_CONFLICT", "message": "Duplicate idempotency key." } } ``` Examples: * Duplicate transaction * Duplicate account identifier * Duplicate external reference *** ### INSUFFICIENT\_FUNDS The account does not have enough available balance. ```json { "statusCode": 422, "statusMessage": "Business Rule Violation", "error": { "code": "INSUFFICIENT_FUNDS", "message": "The source account has insufficient available balance." } } ``` *** ### CURRENCY\_MISMATCH The transaction contains accounts with incompatible currencies. ```json { "statusCode": 422, "statusMessage": "Business Rule Violation", "error": { "code": "CURRENCY_MISMATCH", "message": "All transaction entries must use the same currency." } } ``` *** ### INVALID\_TRANSACTION\_STATE The requested operation cannot be performed because of the transaction's current state. ```json { "statusCode": 422, "statusMessage": "Business Rule Violation", "error": { "code": "INVALID_TRANSACTION_STATE", "message": "Completed transactions cannot be modified." } } ``` *** ### RATE\_LIMIT\_EXCEEDED The client has exceeded the allowed request rate. ```json { "statusCode": 422, "statusMessage": "Business Rule Violation", "error": { "code": "INVALID_TRANSACTION_STATE", "message": "Completed transactions cannot be modified." } } ``` *** ### INTERNAL\_ERROR An unexpected error occurred while processing the request. ```json { "statusCode": 429, "statusMessage": "Too Many Requests", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Please retry after 60 seconds." } } ``` No changes to your request are required. You may retry the request later. *** ## Error Handling Best Practices To build reliable integrations with the Segment Ledgers API: * Always check the HTTP status code before processing the response body. * Use the `error.code` field for application logic rather than parsing the error message. * Treat `error.message` as human-readable text that may change over time. * Do not assume every error response contains the same message, even for the same error code. * Retry only transient failures such as `429 Too Many Requests`, `500 Internal Server Error`, and `503 Service Unavailable`, using exponential backoff. * Correct client-side errors (`400`, `401`, `403`, `404`, `409`, and `422`) before retrying. * Log the complete error response, along with any request or correlation identifiers, to simplify troubleshooting. *** ## Troubleshooting Guide | Error | Cause | Resolution | | ------------------------- | ---------------------------------- | -------------------------------------------------------------------- | | 400 Bad Request | Missing or invalid request data | Verify the request body and required fields. | | 401 Unauthorized | Invalid or missing API key | Check the `Authorization` header and API credentials. | | 403 Forbidden | Permission denied | Ensure the API key has access to the requested ledger or resource. | | 404 Not Found | Resource does not exist | Verify the resource identifier and endpoint URL. | | 409 Conflict | Duplicate or conflicting operation | Use a unique idempotency key or resolve the existing resource state. | | 422 Unprocessable Entity | Business rule violation | Review account balances, currencies, and transaction state. | | 429 Too Many Requests | Rate limit exceeded | Wait for the `Retry-After` interval before retrying. | | 500 Internal Server Error | Unexpected server issue | Retry the request later. If the problem persists, contact support. | | 503 Service Unavailable | Temporary outage or maintenance | Retry the request after a short delay. |