Error Code Reference
Every status your APIs can return — what it means, and the first thing to check. Print this page and tape it to your monitor.
RUAL APIs answer errors as JSON: an HTTP status, a machine-readable code, and a message. For blueprint-side error handling with success/error pins, see Block Execution; for symptom-led fixes, see Common Issues.
The Error Shape
Error Response
{
"error": "DOCUMENT_NOT_FOUND",
"message": "The requested document does not exist."
}4xx — Caller Side
| Code | Meaning | First thing to check |
|---|---|---|
400 | Bad request — malformed body/params/file | Your JSON against the endpoint's parameter table; content-type header. |
401 | Unauthenticated — missing, expired, or incomplete auth (2FA) | Token present in an accepted location; idle longer than 14 days? 2FA code included? |
403 | Forbidden — valid token, insufficient scope | The endpoint's required scope vs the user's scopes (scoping). |
404 | Endpoint or document not found | Path typos; for custom APIs: blueprint activated? |
409 | Conflict — update-hash/version mismatch | Re-read the document; retry with the current update_hash. |
422 | Unprocessable — semantic validation failed | The response body names the failing field/rule. |
429 | Rate limited | Back off with jittered retries; check per-endpoint limits (rate limiting). |
5xx — Cluster Side
| Code | Meaning | First thing to check |
|---|---|---|
500 | Internal error | Retry once; if persistent, cluster logs in RUAL Studio (All Logs) name the failing block. |
Common Error Strings
| String | Means |
|---|---|
MISSING_RUAL_ENDPOINT | No API is registered at that path/method (typo, wrong method, or inactive blueprint). |
DOCUMENT_NOT_FOUND | The guid doesn't exist (or was removed) in that collection. |
INSUFFICIENT_PERMISSIONS | The token's user lacks the scope this endpoint requires. |
FILE_TOO_BIG | Upload exceeded the 500MB asset limit. |
Blueprint-Side Errors
Blocks fail differently than APIs: every fallible block carries success and error out-pins. The error pin emits a JSON with the failing block's type, message, and context — the full shape is documented in Block Execution — Error Handling, and debugging technique in Debugging Blueprints.