REST API
Errors
The error format of the Brunel REST API, every error code with its HTTP status and meaning, and how to handle them. Generated from the API's own error table.
Format
json
{ "error": { "code": "upgrade_required", "message": "Your plan does not include this, or its monthly quota is used up." } }Handle errors by code, not by message: messages are written for people and may change.
Codes
| Status | Code | Meaning |
|---|---|---|
400 | invalid_arguments | A field is missing or invalid; the message says which. |
401 | auth_required | No API key was sent. |
401 | invalid_api_key | The key is wrong, revoked or expired. |
402 | upgrade_required | Your plan does not include this, or its monthly quota is used up. |
403 | read_only_key | A read-only key called an endpoint that writes. |
403 | ip_not_allowed | The key's IP allow list does not include this address. |
403 | policy_denied | Your team's restricted access refuses this address. |
404 | not_found | Unknown endpoint, or a project you cannot access. |
409 | not_analyzed | Analyze the repository before designing it. |
409 | not_designed | Design the infrastructure before refining it. |
502 | job_failed | The analysis or design failed; the message says why. |
Other codes you may meet:
| Status | Code | Meaning |
|---|---|---|
| 403 | browser_only | The action needs the Brunel web app, not an API key |
| 403 | cross_origin | A browser request came from another site |
| 415 | unsupported_media_type | Send a JSON body with Content-Type: application/json |
| 500 | internal | Unexpected error: retry later and quote the x-request-id |
Handling
4xxerrors other than 429 will fail again unchanged: fix the request or the account.402 upgrade_required: a plan limit or quota; see Plans and limits.409 not_analyzed/not_designed: call the steps in order (analyze, design, refine).502 job_failedand500: retry once after a short wait; if it persists, contact support with thex-request-id.