ATAILA Cloud Platform API

Errors. Every error is a problem document with these members: type, urn:ataila:api:problem:<code>, an identifier rather than a link; title, the HTTP status phrase; status, the HTTP status again; detail, what went wrong this time, for a person, worded freely; code, the stable reason to branch on; instance, the request path; and request_id, the same as the X-Request-ID header. Some codes add members, named below; ignore any member you do not know. Each operation names its own codes in its responses. These come from the layers every request passes through, so any operation can answer them:

• 401 not_authenticated: no Authorization header, or not Bearer <token>. 401 token_invalid: the token is malformed or unknown, or a session token does not verify (an expired one included). 401 token_expired and token_revoked: the API token has expired or was revoked. 401 principal_disabled: the account behind the token or session is deactivated. 401 token_ip_not_allowed: the token's address allowlist does not include the caller. A 401 carries WWW-Authenticate: Bearer; retrying with the same credential does not help.
• 403 forbidden: the operation needs a permission the caller lacks; required lists the permission keys, any one of which would do. A token holds only those of its scopes its owner still holds. 403 destroy_not_allowed: a destroy (archive, delete, deactivate, retire) with a token created without allow_destroy.
• 403 licence_locked: the licence has expired or was revoked, so every change is refused except installing a licence (PUT /licence/bundle). 403 licence_restricted: this platform is not licensed yet, so nothing that grows it (customers, tenants, projects, releases, AI) can be added or changed. 403 licence_required: the licence lacks a module the operation needs, named in entitlement. 403 licence_refused: any other licence refusal. Each carries state (the licence state), state_reason, remedy (what an operator must do) and remedy_url. A read is never refused for a licence reason. Never retry a licence_* code: only a licence change alters the answer.
• 400 invalid_idempotency_key: the Idempotency-Key is not 1-255 printable characters. 409 idempotency_key_reused: the key was used for a different request (method, path, query or body) in the last 24 hours. 429 idempotency_request_in_progress: the first request with the key is still running.
• 400 invalid_cursor: the cursor is not one this list issued.
• 422 validation_failed: the request does not match the schema; errors lists each failure (loc, msg, type) and field names the first offending member. 422 immutable_field: a change to a field that is frozen once created; field names it.
• 429 rate_limited: more than 600 requests in a minute with this token.
• 503 unavailable: the platform cannot answer right now. 503 api_tokens_unconfigured: API tokens are not configured on this platform; an operator must act, and retrying does not help.
• 404 not_found: every path, this document and the interactive reference included, while the public API is switched off on this platform; and any path that does not exist. 405 method_not_allowed: the path exists, the method does not. 500 internal_error: an unexpected failure, with no detail; request_id finds it in the server log.

A 429 and a 503 carry Retry-After (seconds) when a retry can succeed: wait that long, then send the same request again. When no specific code applies, code is the one for the status: bad_request (400), not_authenticated (401), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), gone (410), precondition_failed (412), unsupported_media_type (415), validation_failed (422), rate_limited (429), internal_error (500), bad_gateway (502), unavailable (503) and gateway_timeout (504).