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.

{
  "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

{
  "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

{
  "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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.