> 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/status-code.md). # Status Code Every API request returns an HTTP status code indicating whether the request was successfully processed. A successful request returns a **2xx** status code, while invalid requests, authentication failures, validation errors, or server-side issues return **4xx** or **5xx** responses. In addition to the HTTP status code, Segment Ledgers returns a standardized JSON response body containing detailed information about the result of the request. ## Response Format All API responses follow a consistent structure. ### Successful Response ```json { "statusCode": 200, "statusMessage": "Success", "payload": { ... } } ``` ### Error Response ```json { "statusCode": 400, "statusMessage": "Validation Error", "error": { "code": "VALIDATION_ERROR", "message": "ledger_id is required" } } ``` ## HTTP Status Codes | Status Code | Name | Description | | ----------- | --------------------- | ------------------------------------------------------------------------------------------------------ | | **200** | OK | The request completed successfully. | | **201** | Created | A new resource was successfully created. | | **202** | Accepted | The request has been accepted for processing. | | **204** | No Content | The request completed successfully and no response body is returned. | | **400** | Bad Request | The request is invalid or contains missing or malformed parameters. | | **401** | Unauthorized | Authentication failed or no API key was provided. | | **403** | Forbidden | The authenticated client does not have permission to access the requested resource. | | **404** | Not Found | The requested resource does not exist. | | **409** | Conflict | The request conflicts with the current state of the resource (for example, duplicate idempotency key). | | **422** | Unprocessable Entity | The request is syntactically valid but contains invalid business data. | | **429** | Too Many Requests | Rate limit exceeded. Retry after the specified interval. | | **500** | Internal Server Error | An unexpected server error occurred. | | **503** | Service Unavailable | The service is temporarily unavailable or undergoing maintenance. | | | | | ## Success Responses ### 200 OK Returned when a request completes successfully. #### Example ``` HTTP/1.1 200 OK ``` ```json { "statusCode": 200, "statusMessage": "Success", "payload": { "id": "led_4fd32d2d", "name": "Main Ledger" } } ``` ### 201 Created Returned after successfully creating a new resource. #### Example ``` HTTP/1.1 201 Created ``` ```json { "statusCode": 201, "statusMessage": "Ledger created successfully", "payload": { "id": "led_4fd32d2d", "name": "Production Ledger" } } ``` *** ### 202 Accepted Returned when a request has been accepted but processing has not yet completed. This is commonly used for asynchronous operations. ``` HTTP/1.1 202 Accepted ``` ```json { "statusCode": 202, "statusMessage": "Transaction accepted for processing", "payload": { "transaction_id": "txn_8ab39d2f", "status": "PENDING" } } ``` *** ### 204 No Content Returned when an operation succeeds but no response body is required. Typical examples include: * Delete operations * Some update operations ``` HTTP/1.1 204 No Content ``` *** ## Client Errors (4xx) Client errors indicate that the request cannot be processed due to invalid input, authentication failures, or insufficient permissions. *** ### 400 Bad Request Returned when the request is malformed or required parameters are missing. #### Common Causes * Missing required fields * Invalid JSON * Incorrect parameter format * Invalid UUID * Unsupported query parameter #### Example ``` HTTP/1.1 400 Bad Request ``` ```json { "statusCode": 400, "statusMessage": "Bad Request", "error": { "code": "INVALID_REQUEST", "message": "ledger_id is required" } } ``` *** ### 401 Unauthorized Returned when authentication credentials are missing or invalid. #### Common Causes * Missing Authorization header * Invalid API key * Expired API key * Invalid signature #### Example ``` HTTP/1.1 401 Unauthorized ``` ```json { "statusCode": 401, "statusMessage": "Unauthorized", "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } } ``` *** ### 403 Forbidden Returned when authentication succeeds but access to the resource is denied. #### Example ``` HTTP/1.1 403 Forbidden ``` ```json { "statusCode": 403, "statusMessage": "Forbidden", "error": { "code": "ACCESS_DENIED", "message": "You do not have permission to access this ledger." } } ``` *** ### 404 Not Found Returned when the requested resource cannot be found. #### Example ``` HTTP/1.1 404 Not Found ``` ```json { "statusCode": 404, "statusMessage": "Not Found", "error": { "code": "RESOURCE_NOT_FOUND", "message": "Ledger not found." } } ``` *** ### 409 Conflict Returned when the request conflicts with an existing resource or operation. Examples include: * Duplicate idempotency key * Duplicate account identifier * Transaction already processed #### Example ``` HTTP/1.1 409 Conflict ``` ```json { "statusCode": 409, "statusMessage": "Conflict", "error": { "code": "RESOURCE_CONFLICT", "message": "A transaction with this idempotency key already exists." } } ``` *** ### 422 Unprocessable Entity Returned when validation succeeds but business rules prevent the operation. Examples include: * Insufficient balance * Currency mismatch * Invalid transaction state * Closed account * Unsupported account type #### Example ``` HTTP/1.1 422 Unprocessable Entity ``` ```json { "statusCode": 422, "statusMessage": "Validation Error", "error": { "code": "INSUFFICIENT_FUNDS", "message": "The source account does not have sufficient available balance." } } ``` *** ### 429 Too Many Requests Returned when the client exceeds the permitted API request rate. The response may include a `Retry-After` header indicating how long to wait before retrying. #### Example ``` HTTP/1.1 429 Too Many RequestsRetry-After: 60 ``` ```json { "statusCode": 429, "statusMessage": "Too Many Requests", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please retry later." } } ``` *** ## Server Errors (5xx) Server errors indicate that the request was valid but could not be completed due to an unexpected problem within Segment Ledgers. *** ### 500 Internal Server Error Returned when an unexpected server-side error occurs. ``` HTTP/1.1 500 Internal Server Error ``` ```json { "statusCode": 500, "statusMessage": "Internal Server Error", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred." } } ``` *** ### 503 Service Unavailable Returned when the service is temporarily unavailable due to maintenance or temporary capacity issues. ``` HTTP/1.1 503 Service Unavailable ``` ```json { "statusCode": 503, "statusMessage": "Service Unavailable", "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Please try again later." } } ```