Skip to content
Theme
Upload a photo Upload
Theme
Theme
Upload a photo

Developers

Errors

Every API error is RFC 9457 Problem Details with a stable code and a request_id. How to read and handle them.

On this page
  1. The fields
  2. Examples
  3. Status codes
  4. Handle errors in code
  5. Every error code

When a request fails, the API answers with a 4xx or 5xx status and a Problem Details body (RFC 9457), with the content type application/problem+json. Every error has the same shape, so one handler covers them all.

401 Unauthorized
{
  "type": "https://studio.mutexai.net/docs/api/errors#invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The API key is missing, malformed, revoked or expired.",
  "code": "invalid_api_key",
  "request_id": "01JD3YB6H0N4XQ2D8W5M7K9P3R"
}

The fields#

FieldWhat it is
typeA link to this error on the error codes page.
titleThe HTTP status in words.
statusThe HTTP status code, repeated in the body.
detailA sentence for people: what went wrong and what to do. It may change, so do not match on it.
codeA stable code for your program to check, such as insufficient_scope. Codes are never renamed. New codes may be added.
request_idThe same value as the X-Request-Id header. Quote it when you contact us.
errorsOnly on 422 validation_failed: a list of messages for each field.

Some errors add fields that help you act: required_scope on insufficient_scope, credits_needed and credits_available on insufficient_credits, and reason on webhook_url_not_allowed.

Examples#

422 validation_failed
{
  "type": "https://studio.mutexai.net/docs/api/errors#validation_failed",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Some fields are not valid.",
  "code": "validation_failed",
  "request_id": "01JD3YC1T5V7X9Z2B4D6F8H0J2",
  "errors": {
    "url": ["The URL must start with https://."],
    "events.0": ["This is not an event type we send."]
  }
}
403 insufficient_scope
{
  "type": "https://studio.mutexai.net/docs/api/errors#insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key does not have the ledger:read scope.",
  "code": "insufficient_scope",
  "request_id": "01JD3YD0K2M4P6R8T0V2X4Z6B8",
  "required_scope": "ledger:read"
}
402 insufficient_credits
{
  "type": "https://studio.mutexai.net/docs/api/errors#insufficient_credits",
  "title": "Payment Required",
  "status": 402,
  "detail": "This request needs 7 credits; your available balance is 3.",
  "code": "insufficient_credits",
  "request_id": "01JD3YE4N6Q8S0U2W4Y6A8C0E2",
  "credits_needed": 7,
  "credits_available": 3
}

Status codes#

StatusMeaningRetry?
400The request could not be read, or a header is wrong.No. Fix it.
401The key is missing, wrong, revoked or expired.No.
402Not enough credits, or the key's monthly cap is reached.After a top-up.
403The key or account may not do this (scope, IP, account status).No.
404No such path, or no such object in this account and mode.No.
405Wrong HTTP method for this path.No.
409A conflict: a request with the same idempotency key is running, or a limit was reached.For request_in_progress, yes.
422The fields are not valid, or an idempotency key was reused.No. Fix it.
429Too many requests.Yes, after Retry-After.
5xxOur fault. Nothing internal is shown.Yes, with backoff and the same idempotency key.

Handle errors in code#

Branch on code, not on detail or the status alone, and always log request_id.

PHP
<?php

/**
 * Decides what to do with a failed API response. $status is the HTTP status and $problem the
 * decoded application/problem+json body. Always log $problem['request_id'].
 */
function handleStudioError(int $status, array $problem): string
{
    return match (true) {
        $problem['code'] === 'rate_limited' => 'retry after the Retry-After header',
        $problem['code'] === 'request_in_progress' => 'retry the same request in a second',
        $problem['code'] === 'insufficient_credits' => 'ask the account owner to buy credits',
        $problem['code'] === 'validation_failed' => 'fix the fields in $problem["errors"]',
        in_array($problem['code'], ['invalid_api_key', 'ip_not_allowed', 'insufficient_scope'], true) => 'fix the key or its settings',
        $status >= 500 => 'retry with backoff and the same Idempotency-Key',
        default => 'do not retry; fix the request',
    };
}
JavaScript
// Decides what to do with a failed API response. Always log problem.request_id.
export function handleStudioError(status, problem) {
  switch (problem.code) {
    case 'rate_limited':
      return 'retry after the Retry-After header';
    case 'request_in_progress':
      return 'retry the same request in a second';
    case 'insufficient_credits':
      return 'ask the account owner to buy credits';
    case 'validation_failed':
      return 'fix the fields in problem.errors';
    case 'invalid_api_key':
    case 'ip_not_allowed':
    case 'insufficient_scope':
      return 'fix the key or its settings';
    default:
      return status >= 500 ? 'retry with backoff and the same Idempotency-Key' : 'do not retry; fix the request';
  }
}

Every error code#

The full list, with the status each one uses, is on the API error codes page. Each code has its own anchor, which is also the link in the error's type field.

Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.

Type at least 2 letters. Use the arrow keys to move and Enter to open.

    Type at least 2 letters. Use the arrow keys to move and Enter to open.