Errors

API errors are sanitized, request-correlated responses. Internal exceptions, SQL, filesystem paths, secrets, and stack traces are not part of the public error body.

Envelope

API failures use error.code, error.message, error.request_id, and the top-level request_id. X-Request-ID is server-owned. A valid X-Correlation-ID is echoed for tracing.

text

{
  "error": {"code": "invalid_request", "message": "The request is invalid.", "request_id": "req_YOUR_REQUEST"},
  "request_id": "req_YOUR_REQUEST"
}

Implemented status conventions

401 unauthenticated; 403 forbidden, insufficient_scope, or environment_mismatch; 404 not_found; 415 unsupported_media_type; 422 validation/query/request errors; 409 idempotency_conflict and implemented webhook operation conflicts; 429 rate_limited; 500 internal_error for unexpected failures.

Validation and ownership

Invalid JSON content type, malformed fields, unsupported statuses or filters, invalid API keys, unsafe webhook URLs, invalid Idempotency-Key values, and invalid environment operations are rejected with sanitized messages. Merchant ownership is checked after authentication and before resource access.

Safe client behavior

Branch on the status and stable code, log request_id, correct 4xx input, use bounded backoff for retryable delivery failures, and avoid tight loops on 429. Do not parse message text as a stable contract or expose error responses to end users without review.