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 Response
{
  "error": "DOCUMENT_NOT_FOUND",
  "message": "The requested document does not exist."
}

4xx: the caller has to change something

CodeMeaningFirst thing to check
400Bad request: malformed body, params or fileYour JSON against the endpoint's parameter table; content-type header.
401Unauthenticated: missing, expired or incomplete auth (2FA)Token present in an accepted location; idle longer than 14 days? 2FA code included?
403Forbidden: valid token, insufficient scopeThe endpoint's required scope against the user's scopes (scoping).
404Endpoint or document not foundPath typos; for custom APIs: blueprint activated?
409Conflict: update-hash or version mismatchRe-read the document; retry with the current update_hash.
422Unprocessable: semantic validation failedThe response body names the failing field or rule.
429Rate limitedBack off with jittered retries; check per-endpoint limits (rate limiting).

5xx: something failed on the cluster

CodeMeaningFirst thing to check
500Internal errorRetry once; if persistent, cluster logs in RUAL Studio (All Logs) name the failing block.

Common error strings

StringMeans
MISSING_RUAL_ENDPOINTNo API is registered at that path and method (typo, wrong method, or inactive blueprint).
DOCUMENT_NOT_FOUNDThe guid doesn't exist (or was removed) in that collection.
INSUFFICIENT_PERMISSIONSThe token's user lacks the scope this endpoint requires.
FILE_TOO_BIGUpload 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.