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

{
  "statusCode": 200,
  "statusMessage": "Success",
  "payload": {
    ...
  }
}

Error Response

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

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

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

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

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

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

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

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

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

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

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

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

{
  "statusCode": 503,
  "statusMessage": "Service Unavailable",
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please try again later."
  }
}