Errors

Sigmora uses conventional HTTP status codes and returns a JSON body on every failure. The status tells you the class of problem; the code tells you exactly which one, and it is the field your client should branch on.

Error shape

{
  "success": false,
  "error": "Not enough credits: text.script costs 150. Top up to continue.",
  "code": "insufficient_credits",
  "details": { "required": 150, "available": 40 }
}

Field	Type	Description
`success`	`false`	Always `false` on a failure. Successful responses carry `success: true` next to their fields.
`code`	string	Stable, machine-readable cause. Branch on this.
`error`	string	A sentence for people. Its wording can change between releases, so never match on it.
`details`	object	Optional structured context, such as the credit shortfall or field-level validation errors.
`requestId`	string	Identifies the request in our logs. Include it when you contact support.
`timestamp`	string	When the failure was produced, as an ISO 8601 date-time.

Responses may gain fields over time. Ignore fields you do not recognize.

Error codes

Status	`code`	What to do
`400`	`invalid_request`	Fix the request. The body, query or a header failed validation; `details` names the field. Do not retry unchanged.
`401`	`unauthorized`	Send a valid key as `Authorization: Bearer sk_live_...`.
`403`	`forbidden`	The key is valid but its role or scope does not allow this operation.
`403`	`origin_not_allowed`	A browser request came from an origin that is not allowed. Call the API from your server.
`404`	`not_found`	The resource does not exist or belongs to another workspace. The two are deliberately indistinguishable.
`409`	`conflict`	An `Idempotency-Key` was reused with a different body, the same request is still in flight, or the resource is in a state that does not allow the change.
`413`	`payload_too_large`	The body is over the accepted size.
`402`	`insufficient_credits`	The workspace balance is below the price. Top up, then retry.
`402`	`budget_capped`	A budget policy caps this user or team. Topping up does not help; raise the budget in the dashboard.
`422`	`content_not_cleared`	The work ran, but a content check withheld the output (a `video.remix` script with `verify: true` that the fact-check did not clear). Nothing is charged; `details.gate` says why. Do not retry unchanged: the same `Idempotency-Key` returns the same answer.
`429`	`rate_limited`	Wait for the number of seconds in `Retry-After`, then retry. See Rate limits.
`503`	`upstream_unavailable`	A dependency is temporarily unreachable. Retry with backoff; honor `Retry-After` when present.
`503`	`capability_unavailable`	This operation cannot be served right now. Retrying will not help — check `available` in `GET /v1/capabilities`.
`500`	`upstream_error`	A dependency failed in a way we could not translate. Safe to retry once with the same `Idempotency-Key`; report it if it persists.
`500`	`internal_error`	A fault on our side. Report it with the `x-request-id` response header.

The list of codes only grows: a code is never renamed or removed within v1. Treat a code you do not recognize by its HTTP status. Several codes share a status but call for opposite responses — the reason to branch on code rather than on the status:

402 — insufficient_credits clears when you top up; budget_capped does not.
503 — upstream_unavailable is worth retrying; capability_unavailable never is.
403 — forbidden is about the key; origin_not_allowed is about where the request came from.

Handling errors

curl -s https://api.sigmora.org/v1/projects/prj_does_not_exist \
  -H "Authorization: Bearer $SIGMORA_API_KEY"
# {"success":false,"error":"No such project.","code":"not_found"}

import os
import requests

response = requests.get(
    "https://api.sigmora.org/v1/projects/prj_9x2a4c",
    headers={"Authorization": f"Bearer {os.environ['SIGMORA_API_KEY']}"},
    timeout=30,
)
body = response.json()

if not response.ok:
    code = body.get("code")
    if code == "rate_limited":
        retry_after = int(response.headers.get("Retry-After", "1"))
        ...  # wait retry_after seconds, then retry
    elif code == "insufficient_credits":
        ...  # ask the workspace owner to top up
    else:
        raise RuntimeError(
            f"{code}: {body.get('error')} (request {response.headers.get('x-request-id')})"
        )

const response = await fetch("https://api.sigmora.org/v1/projects/prj_9x2a4c", {
  headers: { Authorization: `Bearer ${process.env.SIGMORA_API_KEY}` },
});
const body = await response.json();

if (!response.ok) {
  switch (body.code) {
    case "rate_limited": {
      const retryAfter = Number(response.headers.get("Retry-After") ?? "1");
      // wait retryAfter seconds, then retry
      break;
    }
    case "insufficient_credits":
      // ask the workspace owner to top up
      break;
    default:
      throw new Error(`${body.code}: ${body.error} (request ${response.headers.get("x-request-id")})`);
  }
}

Validation details

An invalid_request caused by a schema failure carries field-level detail in details, so you can point at the offending field instead of diffing your payload against the reference:

{
  "success": false,
  "error": "Invalid body",
  "code": "invalid_request",
  "details": { "fieldErrors": { "domain": ["Invalid enum value."] } }
}

Retrying safely with idempotency keys

Send an Idempotency-Key header on every call that spends credits or creates something. Use a value that identifies the logical operation in your system — a UUID you store alongside the work is ideal — and reuse it when you retry.

Situation	Response
Same key, same body, the first call finished	The stored response is replayed with an `Idempotent-Replay: true` header. No second charge, no second run.
Same key, same body, the first call is still running	`409 conflict` — one logical call is already in flight. Wait, then retry.
Same key, different body	`409 conflict` — the key already answers a different request.

A call that failed does not hold its key: it delivered nothing and charged nothing, so retrying it with the same key genuinely retries. Some operations require the header and answer 400 invalid_request without it — including POST /v1/projects, POST /v1/autopilot-runs, POST /v1/assets/import and POST /v1/webhook-subscriptions. The API reference marks the header as required on each of them.

Retry unchanged only on rate_limited and upstream_unavailable, and on network failures where you still hold the idempotency key. A failure to verify your credential against a store we could not reach is reported as upstream_unavailable with Retry-After, never as unauthorized — the fault is ours and it clears.

Request IDs

Every response carries an x-request-id header. Log it, and include it when you contact support about a specific call.

Get started

Create

Grow & automate

Integrate

Build reliably

Operate

Error shape

Error codes

Handling errors

Validation details

Retrying safely with idempotency keys

Request IDs

​Error shape

​Error codes

​Codes that share a status

​Handling errors

​Validation details

​Retrying safely with idempotency keys

​Request IDs

Error shape

Error codes

Codes that share a status

Handling errors

Validation details

Retrying safely with idempotency keys

Request IDs