Handle failures with the problem code and request ID

Errors use application/problem+json. The HTTP status classifies the transport outcome, while the stable code identifies the recovery path. Save requestId or correlationId when escalating a failure.

{
  "type": "https://docs.data.hyran.co/problems/invalid_token",
  "title": "The request was rejected",
  "status": 401,
  "detail": "A bearer API token is required.",
  "code": "invalid_token",
  "requestId": "4d34680e-64c8-44ec-994d-a1352c6569b4",
  "correlationId": "4d34680e-64c8-44ec-994d-a1352c6569b4",
  "retryable": false,
  "recovery": "Replace or rotate the credential, then retry without changing tenant inputs."
}

Retry decisions

Status	Default action
`400`	Correct the documented fields. Do not retry the same request.
`401`	Replace or rotate the credential.
`403`	Request the required scope or use the issued regional origin.
`404`	Confirm the canonical object ID and its availability window.
`409`	Re-read the resource before deciding whether to retry.
`429`	Wait for `Retry-After`, then use bounded exponential backoff.
`500` or `503`	Retry only when `retryable` is true. Preserve the request ID.

POST /v1/exports does not accept an idempotency key in V1. If a client loses the response after sending the body, do not automatically repeat the POST. Check owned export jobs or ask Hyran support to correlate the request ID first.

Rate limits

Each API credential receives 600 requests in the current one-minute UTC bucket. Successful protected responses return RateLimit, RateLimit-Policy, and V1 compatibility headers. A rate-limited request returns 429, a zero remaining count, and Retry-After in seconds.