Errors

Supplier API normalizes most service and HTTP exceptions into structured JSON responses.

Primary error shapes

Domain/HTTP normalized

{
  "error": "not_found",
  "message": "Order not found"
}

Middleware auth response

Some auth failures return:

{
  "detail": "Not authenticated"
}

Clients should handle both shapes.

Common status codes

Status	Typical meaning
400	Validation or business rule failure
401	Missing/invalid auth token
403	Forbidden (unverified supplier on exchange, MFA, disabled route, capability)
404	Resource not found in supplier scope
409	State conflict (invalid lifecycle transition)
422	Request schema validation error
429	Rate limited (edge/gateway or app policy) — back off and retry
500	Internal error
503	Dependency unavailable (auth backend, delegated connection service, etc.)

Domain error codes

Examples include:

• not_found
• access_denied
• validation_error
• business_rule_violation
• invalid_state
• expired
• insufficient_balance
• conflict

Integration recommendations

1. Branch on machine-readable error or fallback detail.
2. Treat 409 as workflow conflict: refresh entity state before retry.
3. Do not blind-retry other 4xx.
4. Retry idempotent reads on transient 5xx/503 with bounded backoff.
5. On 429, honour Retry-After when present; use exponential backoff otherwise.