Errors

Every failed request returns the same JSON body.

{
  "trace_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "error_code": "devapi_not_found_error",
  "message": "Not Found",
  "details": "The customer does not belong to this partner"
}

Status codes

Codes

Validation errors

A 422 lists every invalid field in details:

{
  "trace_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "error_code": "devapi_request_validation_error",
  "message": "Unprocessable Entity",
  "details": [
    {
      "loc": ["body", "source", "amount"],
      "msg": "Input should be a valid decimal",
      "type": "decimal_parsing"
    },
    {
      "loc": ["body", "destination", "client_account_uuid"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

loc is the path to the field: the first item is where the value came from (body, query, header), the rest is the path inside it.

Codes raised by other services

Requests that touch orders, limits, accounts, customers or verification go through internal services, and their codes reach you through the Partner API: oa_ for operations, ca_ for customers. An example is oa_limit_exceeded_error, which check-limits and order creation return when a rule is broken, with the reason in details.

Treat these codes as opaque. Log the code and the trace_id, show the customer message, and send both to support when the problem needs us.

Retries

• Retry 500, 503 and timeouts with exponential backoff. Three attempts is enough for an interactive flow; a background job can keep going longer.
• Send the same Idempotency-Key on every retry of the same request: a repeated create returns the first result instead of a second order. A retry with a different body answers 422 with devapi_idempotency_key_misuse.
• Do not retry 400, 401, 403, 404 and 422 unchanged: the same request fails the same way.
• 409 may go away when the object changes state, so re-read the object before you decide.
• There is no rate limit today. If one appears, it will answer 429 with Retry-After.

The request id header

Every response carries X-Request-Id. Send your own value in the request header and Stablegate returns it unchanged; without it the platform generates one. The trace_id of an error body is the same value, so the header alone identifies the call even when the body never reaches you — for example a gateway timeout.

curl https://api.stablegate.com/v1/customers/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Request-Id: order-c1d2e3f4-42"

Before you contact support

Send the trace_id, the method and path of the request, and the time with the time zone. The trace_id finds the request in our logs, everything else narrows the search.