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
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.
{
"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#
| Field | What it is |
|---|---|
type | A link to this error on the error codes page. |
title | The HTTP status in words. |
status | The HTTP status code, repeated in the body. |
detail | A sentence for people: what went wrong and what to do. It may change, so do not match on it. |
code | A stable code for your program to check, such as insufficient_scope. Codes are never renamed. New codes may be added. |
request_id | The same value as the X-Request-Id header. Quote it when you contact us. |
errors | Only 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#
{
"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."]
}
}
{
"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"
}
{
"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#
| Status | Meaning | Retry? |
|---|---|---|
400 | The request could not be read, or a header is wrong. | No. Fix it. |
401 | The key is missing, wrong, revoked or expired. | No. |
402 | Not enough credits, or the key's monthly cap is reached. | After a top-up. |
403 | The key or account may not do this (scope, IP, account status). | No. |
404 | No such path, or no such object in this account and mode. | No. |
405 | Wrong HTTP method for this path. | No. |
409 | A conflict: a request with the same idempotency key is running, or a limit was reached. | For request_in_progress, yes. |
422 | The fields are not valid, or an idempotency key was reused. | No. Fix it. |
429 | Too many requests. | Yes, after Retry-After. |
5xx | Our 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
/**
* 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',
};
}
// 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.