Every code, one table
Errors
Errors are JSON with a stable machine code, a human message, and — for validation failures — a per-field errors object. The code is the contract; messages may improve between releases, codes never change meaning.
{
"error": {
"code": "scope_denied",
"message": "Run requested context:finance; key grants context:documents.",
"doc_url": "https://myndlabs.ai/docs/errors#scope_denied"
}
}Error codes
| status | code | meaning | what to do |
|---|---|---|---|
| 400 | invalid_request | A field failed validation; errors names each one. | Fix the named fields; do not retry as-is. |
| 401 | unauthenticated | Missing, malformed, or revoked key. | Check the Authorization header and key status. |
| 403 | scope_denied | A fetch or action exceeded the key's scopes. | Grant the named scope or remove the context source. |
| 404 | not_found | Resource does not exist in this project. | Check the id and that you are on the right project. |
| 409 | conflict | State conflict — e.g. run already deleted, duplicate webhook URL. | Read current state before retrying. |
| 409 | idempotency_mismatch | Same Idempotency-Key, different request body. | Use a new key for a genuinely new request. |
| 422 | step_limit | The plan cannot fit within max_steps. | Raise the ceiling or narrow the prompt. |
| 422 | schema_unsatisfiable | Output cannot satisfy the declared schema. | Loosen the schema or revise the prompt. |
| 429 | rate_limited | Bucket exhausted for the window. | Honor Retry-After; back off with jitter. |
| 500 | internal | Our fault; safe to retry with the same Idempotency-Key. | Retry; if persistent, check /status. |
| 503 | overloaded | Temporary capacity pressure on deep runs. | Retry with backoff or fall back to y0-fast. |
Retry discipline
- 4xx except 429: do not retry without changing the request
- 429: retry after Retry-After, with jitter
- 5xx: retry with the same Idempotency-Key — creation is exactly-once
- Log error.code, not error.message, in your metrics