API Documentation

Errors

One JSON error shape with error, message and retryable; every code with its HTTP status; when to retry.

Every error the API answers is JSON with the same shape, the one Magister's MCP tools use:

json

{
  "error": "rate_limited",
  "message": "Rate limit of 60 requests a minute exceeded for this organization.",
  "retryable": true,
  "retry_after_seconds": 12,
  "reason": "rate_limited"
}

- error is a stable code (below); branch on it, not on message, which is for people.

- retryable says whether the same request may succeed later. Retry only when it is true, and after retry_after_seconds when it is given (a 429 also sends Retry-After). Otherwise fix the request, your balance or your access first.

- Some errors add details: reason, required_scope, available_credits, top_up_url, estimated_credits, request_id, or fields for a body that does not fit the schema.

- A request that fails on Magister's side after it started (500 upstream_failed with request_id) is not retryable: the work may have run and been charged. Look it up in Settings → Developers → Requests before sending it again. A path that does not exist answers 404 not_found, and a wrong method 405 unsupported_operation.

json

{
  "error": "validation_error",
  "message": "domain: Field required",
  "retryable": false,
  "fields": [{ "field": "domain", "message": "Field required" }]
}

HTTP statuses

- 401: Missing, unknown or revoked API key.

- 402: Not enough API credits (limit_reached, credits_exhausted, with top_up_url), over max_credits, or a hold above the key's whole daily cap (key_daily_cap_too_low).

- 403: The key lacks a scope, or the endpoint is not enabled.

- 404: Unknown job; or the API is not enabled.

- 409: Not ready yet: the report of a job that has not finished.

- 422: Invalid input (validation_error, with fields when the body does not fit the schema).

- 429: 60 requests a minute or 5 running jobs per organization, or the key's daily cap; see Retry-After.

- 500: The request failed unexpectedly (upstream_failed): retryable when it failed before it started; after, retryable is false and the error carries its request_id.

- 502: An upstream provider failed. Billed only what it used before failing.

- 503: The request could not start (transport_unavailable).

Error codes

Code	HTTP	When	Retry
`not_authenticated`	401	No key, an unknown or revoked key, or a key whose creator left the organization.	no
`budget_exhausted`	402	Passed through from the tool behind the endpoint.	varies
`limit_reached`	402	Not enough API credits (`reason: credits_exhausted`, with `available_credits` and `top_up_url`), the hold is above your `max_credits` (`reason: max_credits_exceeded`, with `estimated_credits`), or the hold is above the whole daily cap of the key, so that key can never start it (`reason: key_daily_cap_too_low`, with `estimated_credits` and `daily_cap_credits`). Nothing ran and nothing was charged.	no
`payment_required`	402	Passed through from the tool behind the endpoint.	varies
`entitlement_unavailable`	403	The API is not open to your organization yet, the endpoint is not available yet, or an AI engine you asked for is not enabled.	no
`forbidden`	403	Passed through from the tool behind the endpoint.	varies
`not_authorized`	403	The key lacks the scope the endpoint needs (`required_scope`).	no
`not_found`	404	The API is switched off, or no such job or set (in this project).	no
`project_not_found`	404	No such brand in this organization.	no
`approval_required`	409	Passed through from the tool behind the endpoint.	varies
`browser_unavailable`	409	Passed through from the tool behind the endpoint.	varies
`conflict`	409	Passed through from the tool behind the endpoint.	varies
`needs_connection`	409	Passed through from the tool behind the endpoint.	varies
`not_ready`	409	The report of a job that has not succeeded.	no
`plan_missing`	409	Passed through from the tool behind the endpoint.	varies
`asset_invalid`	422	Passed through from the tool behind the endpoint.	varies
`needs_media`	422	Passed through from the tool behind the endpoint.	varies
`unsupported_operation`	422	Passed through from the tool behind the endpoint.	varies
`validation_error`	422	The input is invalid. A body that does not fit the schema lists each problem in `fields`.	no
`quota_exceeded`	429	Passed through from the tool behind the endpoint.	varies
`rate_limited`	429	`reason: rate_limited` (60 requests a minute per organization), `jobs_limit` (5 running jobs per organization) or `key_daily_cap_reached` (the key's daily credit cap, reset at 00:00 UTC). Wait `retry_after_seconds` (also the `Retry-After` header).	yes
`upstream_failed`	502	A provider behind the endpoint failed (502), or the request failed unexpectedly (500; not retryable once it had started, with `request_id`). Billed only what it used.	varies
`transport_unavailable`	503	The request could not start.	varies

Codes marked "passed through" come from the Magister tool behind an endpoint, exactly as its MCP tool returns them. Where Retry says "varies", read retryable in the error itself.