Error Code Reference
RUAL APIs answer an error as JSON: an HTTP status, a machine-readable code and a message. Look up the status or the code here to see what it means and what to check first.
The error shape
{
"error": "DOCUMENT_NOT_FOUND",
"message": "The requested document does not exist."
}4xx: the caller has to change something
| Code | Meaning | First thing to check |
|---|---|---|
400 | Bad request: malformed body, params or 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 against the user's scopes (scoping). |
404 | Endpoint or document not found | Path typos; for custom APIs: blueprint activated? |
409 | Conflict: update-hash or version mismatch | Re-read the document; retry with the current update_hash. |
422 | Unprocessable: semantic validation failed | The response body names the failing field or rule. |
429 | Rate limited | Back off with jittered retries; check per-endpoint limits (rate limiting). |
5xx: something failed on the cluster
| 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 and 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 500 MB asset limit. |
Blocks report errors on out-pins, not as a status
Every fallible block carries success and error out-pins. The error pin emits JSON with the failing block's type, message and context. The full shape is in Block Execution: Error Handling, and the technique in Debugging Blueprints.
Next steps
API Guide Auth and conventions around these codes. Common Issues & Fixes Symptom-led fixes for the frequent failures. Debugging Blueprints Reading error pins and tracing failures.Frequently asked
What does a 403 from a RUAL API mean?
The token is valid but lacks the scope the endpoint requires. Compare the endpoint's required scope against the user's scopes and add the missing one.
What does a 409 from a RUAL API mean?
A conflict: the update_hash or version you sent no longer matches the document. Re-read the document and retry with the current update_hash.
What does the RUAL error DOCUMENT_NOT_FOUND mean?
The guid does not exist, or was removed, in that collection. RUAL APIs answer errors as JSON with a machine-readable code and a message, so callers can branch on the code.
What should I check first on a 429 from a RUAL API?
You are rate limited. Back off with jittered retries and check the per-endpoint limits described in the API Guide.