Reference · § 3.2
3.2Error codes
What Relay error codes mean and how to fix each one.
Errors from the platform carry a machine code in the response body and in relay logs. This page lists the common ones.
Deploy errors
| Code | Meaning | Fix |
|---|---|---|
build_failed | The route bundle did not compile | Read the build log; it includes the file and line |
config_invalid | relay.toml failed validation | The error names the exact key; check Configuration |
quota_exceeded | Plan limit reached | Traffic pauses rather than billing overages; upgrade or wait for reset |
Runtime errors
| Code | Meaning | Fix |
|---|---|---|
route_timeout | Handler exceeded 30 s | Move slow work to a webhook consumer or background job |
route_crash | Unhandled exception in a handler | The log line includes the request id and stack trace |
secret_missing | Handler read an unset secret | relay secrets set in the affected environment |
Auth errors
| Code | Meaning | Fix |
|---|---|---|
token_expired | CLI session ended | relay login again |
key_scope | API key lacks the needed permission | Mint a key with the right scope; deploy-only keys cannot read secrets |
Getting help
If a request misbehaves, grab its request id (present on every error page and log line) and mention it when you contact support. The id lets us find the exact trace.