---
title: "Error Code Reference · RUAL Documentation"
description: "What each error code means and what usually causes it."
canonical: https://docs.rual.nl/reference/error-code-reference
language: en
---

# 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](https://docs.rual.nl/blueprints/block-execution#error-handling); for symptom-led fixes. See [Common Issues](https://docs.rual.nl/troubleshooting/common-issues).

### The Error Shape

```
{
  "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](https://docs.rual.nl/blueprints/remote-access-control)). |
| `404` | Endpoint or document not found | Path typos; for custom APIs: blueprint [activated](https://docs.rual.nl/deployment/how-to-deploy)? |
| `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](https://docs.rual.nl/cluster/api-guide#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](https://docs.rual.nl/blueprints/block-execution#error-handling), and debugging technique in [Debugging Blueprints](https://docs.rual.nl/troubleshooting/debugging).

### Next Steps