Skip to main content

​
Checklist

1

Key and secrets

Store SIGMORA_API_KEY in a secret manager, call the API only from your server, and use a key whose role matches the job — a viewer key for dashboards that only read. See Authentication.
2

An idempotency key for every logical operation

Generate an Idempotency-Key per logical operation, store it with the work in your own database, and reuse it on every retry. A timeout does not prove the server stopped; never mint a new key just because a socket timed out.
3

Timeouts that fit the call

Synchronous text capabilities can take minutes; give them a generous client timeout. Async submissions only need to last until the jobId comes back.
4

Polling with backoff, or webhooks

Poll jobs every 15–30 seconds with jitter, or use webhooks with polling as the fallback. Process both paths idempotently by job id.
5

Error handling by code

Branch on code, retry only what is retryable, and log x-request-id. See Errors.
6

Budget and availability checks

Read GET /v1/capabilities before a batch for live prices, availability and your balance.

​
Throughput

The API allows 100 requests per minute per caller identity, shared by every key of the same person. A 429 carries Retry-After; pause all work for that identity for that long. Coordinate workers through a shared queue rather than letting each guess at the limit, and do not spread work across extra keys to get around it. For sustained volume above the limit, contact Sigmora before launch. See Rate limits. Run paid generation through a bounded queue. The balance check accounts for credits committed by work already in flight, so parallel calls cannot overspend — but it is a safety net, not a scheduler.

​
Jobs

  • Stop polling on done, cancelled, failed and qa_failed.
  • Stop and notify a person on awaiting_review; more polling cannot advance it.
  • Never publish artifacts from a qa_failed job.
  • Store the job id as the durable reference, not artifact URLs: signed links expire, and polling the job again returns fresh ones.

​
Errors

Retry network failures only when you hold the idempotency key for the request.

​
Lists

Follow nextCursor until it is null; never assume one page is the whole collection. See Pagination.

​
Contract changes

Integrate only with /v1. Generate types from the OpenAPI document, keep a reviewed copy in your repository, and diff it before updating. Allow unknown response fields, and branch only on values documented as stable — job status and error code. See Versioning.