Response Codes

Common Codes

Code	Meaning
200	Request succeeded.
201	Resource or claim created.
400	Invalid request payload, parameter, or required header.
401	Missing or invalid authentication/signature headers.
403	Access forbidden by policy, scope, or allowlist rules.
404	Requested resource not found.
409	Idempotency conflict, in-progress duplicate, or conflict state.
422	Business-rule rejection (for example limit validation).
429	Too many attempts; retry after cooldown.
500	Unexpected server error.

Endpoint-Specific Codes

Some integration endpoints may also return:

Code	Meaning
502	Upstream provider failure.
503	Service temporarily unavailable (including circuit-open conditions).
504	Upstream provider timeout.

Error Envelope

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Notes

• Handle responses by statusCode first, then use message for operator-facing detail.
• Retry only where the endpoint contract indicates safe retry behavior (typically with Idempotency-Key).