API
Errors
Handle authentication, policy, rate and provider failures separately
Octoryn uses HTTP status codes plus a JSON error body. Error bodies may be returned as a top-level object or under detail depending on the boundary that rejected the request; robust clients read both without exposing raw diagnostics to end users.
Error shape
Use the HTTP status as the primary category and the error/code fields for programmatic handling.
{
"detail": {
"error": "rate_limited",
"code": "RATE_LIMITED",
"retry_after_s": 18
}
}Status codes
Treat each class deliberately.
- 400 — malformed request or invalid channel; fix the request before retrying
- 401 — missing, invalid or revoked API key/JWT; codes can include BAD_API_KEY or BAD_JWT
- 403 — authenticated but not authorised by scope or policy; MISSING_SCOPE identifies a scope failure
- 404 — route or resource not found
- 422 — request body failed validation
- 429 — workspace or route rate limit; use retry_after_s when present
- 502/503/504 — eligible upstream or service path failed; bounded retry may be appropriate
Provider and upstream errors
Provider failures can surface as upstream_rate_limited or upstream_error. A policy route may attempt an eligible fallback before returning an error. Do not expose provider response bodies or credentials to product users.
{
"detail": {
"error": "upstream_rate_limited",
"retry_after": 30
}
}Retry guidance
Retry only requests that are safe to repeat. Use exponential backoff with jitter, respect retry_after_s, cap attempts, and stop when the user-facing deadline is exhausted.
- Do not retry 400, 401, 403 or 422 unchanged
- Retry 429 after the supplied delay
- Retry transient 502, 503 or 504 only within a strict attempt budget
- Treat interrupted streams as partial output, not a guaranteed zero-result request
Operational logging
Record timestamp, environment, route, HTTP status, safe error code and request correlation identifier. Never record bearer tokens, provider secrets or unredacted sensitive content.