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.

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.