エラーとリトライ

Every public Beatra error response uses the standard error envelope. The error.code field is one of the stable public values below; the error.retryable boolean tells the client SDK whether a naive retry could succeed.

Branching rules for client SDKs

• retryable: true errors can be retried with the exact same request after a brief backoff. If a Retry-After header is present, honor it.
• retryable: false errors will produce the same outcome on retry; the client must either change the request, fix credentials, or surface the error to the user.
• error.param (when present) is a JSON Pointer (RFC 6901) to the offending field in the request body.
• error.type, error.details, and error.request_id provide the stable family, correction facts, and trace identifier.
• error.message is diagnostic prose, not a branchable contract. For a task that reaches terminal failure after a provider response, it preserves the provider's wording after credential, signed-URL, control-character, and length safety handling.

When present, error.details.recovery adds a branchable action without changing the top-level error envelope. requires_input_change says whether the submitted content must change. client_request_id: new means the corrected or terminal work is a new logical request; otherwise follow retryable and the endpoint's idempotency rules.

{
  "details": {
    "recovery": {
      "action": "fix_arguments_and_resubmit",
      "requires_input_change": true,
      "client_request_id": "new"
    }
  }
}

Auth / Account

Billing

Request validation

Callbacks

Media inputs

Tasks and resources

Idempotency and response mode

Capacity and availability

Asynchronous task failures

A generation can be admitted successfully and later end with status: failed. REST task reads, MCP beatra.tasks.get, and callbacks return the same Task.error object with code, type, message, retryable, optional param, optional details, and request_id. A failed task read is the task's final state, not an MCP protocol error.

model_output_invalid means the model completed successfully but Beatra could not download the generated artifact after 3 attempts. No result artifact is available for that failed task.

MCP tool errors

A failed MCP tool call returns a tool result with isError: true and structuredContent.error carrying the same vocabulary as the REST envelope — code, type, message, retryable, optional param (JSON Pointer into the tool arguments), optional details — plus the JSON-RPC jsonrpc_code. Branch on code and retryable exactly as with REST.

One MCP-only code exists: insufficient_scope (the OAuth grant lacks a required scope; missing_scopes names them — re-run the Beatra device authorization; retrying without re-authorizing cannot succeed). Unexpected server failures surface as internal_error tool results, never as bare HTTP errors.

Generated from 45 public runtime error codes. 24 internal, admin, or provider-ingress codes are intentionally omitted from public docs.

エラーの扱い方

すべてのエラー本体:

{
  "error": {
    "code": "<machine code>",
    "type": "<error family>",
    "message": "<human description>",
    "retryable": true,
    "param": "/field",
    "details": {},
    "request_id": "req_..."
  }
}

• retryable: true -> 短いバックオフ後に同じ Idempotency-Key で 同じリクエスト を再試行可能。Retry-After ヘッダがある場合は 従ってください。429 応答には X-RateLimit-* ヘッダが付きます。
• retryable: false -> 再試行前にリクエストを変えてください。 リトライ不可エラーでループするのはバグです。