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.