Errors & response format

The standard response envelope, the error object, and how to resolve every code the API can return.

Every API response shares the same structure, whether it succeeds or fails. Learn it once and it applies to every endpoint.

The response envelope

Successful responses wrap the result in data, with optional metadata in meta:

{
  "success": true,
  "data": { "id": "clxq1w2e3r4t5y6u7i8o9p0a", "status": "DRAFT" },
  "meta": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
}

Errors carry success: false and an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": {
        "contactName": ["contactName must be longer than or equal to 1 characters"],
        "postalCode": ["Postal code must be 4-6 digits"]
      }
    },
    "timestamp": "2026-07-17T12:00:00.000Z",
    "requestId": "req_abc123"
  }
}

Every error code

Handle errors by code, not by message

const res = await fetch(url, options);
const body = await res.json();

if (!body.success) {
  switch (body.error.code) {
    case "RATES_EXPIRED":
      // refresh rates and retry
      break;
    case "INSUFFICIENT_BALANCE":
      // notify your operations team
      break;
    default:
      log.error(body.error.requestId, body.error.code);
  }
}

Check details.code too

Some validations return 400 INVALID_INPUT with a more specific code nested in error.details.code. Read it when you need to tell the exact case apart: