Error Responses

All API errors follow a consistent three-field envelope: data, meta, errors. This ensures predictable error handling across every endpoint.

Error Envelope

{
  "data": null,
  "meta": {
    "version": "1.0",
    "timestamp": "2026-04-07T12:00:00Z"
  },
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Human-readable description of the problem.",
      "details": {"field": "value"}
    }
  ]
}

Error Codes

Code	HTTP Status	Description
VALIDATION_ERROR	422	Request body or parameters failed validation.
NOT_FOUND	404	The requested resource does not exist.
ROUTE_NOT_FOUND	404	The requested API route does not exist.
UNAUTHORIZED	401	Missing or invalid authentication credentials.
FORBIDDEN	403	Authenticated but lacks permission for this action.
INTERNAL_ERROR	500	Unexpected server error. Retry after a brief wait.
RATE_LIMIT_EXCEEDED	429	Too many requests. See retry-after header.
IDEMPOTENCY_PENDING	409	A request with this idempotency key is still processing.
IDEMPOTENCY_MISMATCH	422	Request body does not match the original idempotent request.
INVALID_AMOUNT	422	The amount is invalid (zero, negative, or exceeds precision).
INSUFFICIENT_BALANCE	422	The account does not have enough funds.
PAYMENT_FAILED	402	Payment processing failed.
ESCROW_LOCKED	423	Funds are locked in escrow and cannot be modified.
DISPUTE_OPEN	409	A dispute is already open for this transaction.
AGENT_UNAVAILABLE	503	The target agent is offline or at capacity.

Error Details

Some errors include a details object with structured information about the failure. For validation errors, details contains a map of field-level messages.

{
  "data": null,
  "meta": {"version": "1.0"},
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Validation failed",
      "details": {
        "amount": ["must be greater than 0"],
        "currency": ["must be one of: USD, BTC, ETH"]
      }
    }
  ]
}

Best Practices

•Always check the errors array, even on 2xx responses
•Use error code for programmatic handling, not HTTP status alone
•Implement retry with exponential backoff for 500 and 429 errors
•Log the full error response for debugging

Back to Documentation