Errors
The error response shape and the HTTP status codes the gateway returns, so you can handle failures predictably.
When a request fails, the gateway answers with a standard HTTP status code and a small JSON body. Handle the status code; show or log the message.
The error shape
Every gateway error has the same two fields:
Error
{
"error": true,
"message": "missing X-Revenexx-Tenant header"
}
A capability can add detail to the message, but the shape stays the same. Always read the status code to decide what to do — the message is for humans and logs.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 Bad Request | The request was malformed — a missing X-Revenexx-Tenant, or a body that failed schema validation. | Fix the request; don't retry unchanged. |
401 Unauthorized | Missing or invalid credential. | Check the API key / token; re-authenticate. |
403 Forbidden | Authenticated, but not allowed — the key's scope doesn't cover this capability, the user isn't a member of the tenant, or the app isn't installed. | Adjust scopes/permissions; don't retry as-is. |
404 Not Found | No capability matches that path for this tenant. | Check the path and that the app is installed. |
429 Too Many Requests | The tenant's rate limit was exceeded. | Honor Retry-After, then back off. |
502 Bad Gateway | The implementing app or an upstream service failed. | Safe to retry with backoff — see Retries & idempotency. |
Include the
X-Request-ID from the response in any support request — it lets us trace exactly what happened.Reading it in code
Handle errors
const res = await fetch(url, { headers })
if (!res.ok) {
const requestId = res.headers.get('x-request-id')
const { message } = await res.json().catch(() => ({}))
throw new Error(`revenexx ${res.status} (${requestId}): ${message ?? 'request failed'}`)
}