API / Guides
Errors
The error envelope and every code.
Errors
Every error inside /api/v1 uses the same envelope. Branch on
code, show message to the
designer: the messages are written for them, not for you.
project_locked
json
{
"error": {
"code": "project_locked",
"message": "This project is locked and cannot be modified. Unlock it from the project page to allow changes."
}
}
not_found
json
{
"error": {
"code": "not_found",
"message": "Resource not found."
}
}
validation_failed
json
{
"error": {
"code": "validation_failed",
"message": "The request payload failed validation.",
"details": {
"type": [
"The type field is required."
],
"component": [
"The component field is required."
]
}
}
}
insufficient_scope
json
{
"error": {
"code": "insufficient_scope",
"message": "This token is missing the required scope: components:write."
}
}
invalid_token
json
{
"error": {
"code": "invalid_token",
"message": "A valid bearer token is required."
}
}
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request |
Malformed input. Fix the request. |
| 401 | invalid_token |
Refresh the token. If refresh fails, send the designer through the consent flow again. |
| 403 | insufficient_scope |
Your token lacks a scope this endpoint needs. Re-authorize asking for it. |
| 403 | plan_limit_reached |
The designer is at their project cap. Show the message, do not retry. |
| 403 | forbidden |
Usually a delete against a component your app did not create. |
| 404 | not_found |
Wrong id, or it belongs to someone else. Deliberately indistinguishable. |
| 409 | project_locked |
The project is read-only. Ask the designer to unlock it. |
| 413 | file_too_large |
Over the 50 MB per-file limit. |
| 422 | validation_failed |
Check details for the per-field reasons. |
| 422 | storage_quota_exceeded |
Out of space. details carries the byte counts. |
| 422 | unsupported_media_type |
Not an accepted image type. |
| 429 | rate_limited |
Back off. Honour the Retry-After header. |
| 500 | server_error |
Our fault. Retry with backoff. |
The OAuth endpoints at /oauth/ are the one exception: they return the standard
RFC 6749 error shape, which is what OAuth client libraries expect.