Errors and retries

Error envelope

Failed Integration API responses use a consistent JSON body:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "status": 400,
    "details": [{ "path": "field", "message": "…" }]
  }
}

details is optional (used for validation issues). Always branch on error.code / HTTP status in clients; do not parse free-text message as a contract.

Common codes

Additional codes may appear; treat unknown codes as generic failures.

Rate limiting

Integration routes are rate-limited per API key and split into separate buckets by HTTP method class:

• Read routes (GET, HEAD): Sized for polling job status and fetching resources.
• Write routes (POST, DELETE, etc.): Separate tighter budget reserved for state-changing operations and GPU generation triggers.

Exhausting your budget on read routes will not block write requests, and vice versa. When limited, responses use RATE_LIMIT_EXCEEDED (HTTP 429) and include standard rate-limiting headers:

• X-RateLimit-Limit — Max capacity for the route class
• X-RateLimit-Remaining — Capacity remaining in the current window
• X-RateLimit-Reset — Unix timestamp (seconds) when the window resets
• Retry-After — Exact seconds to wait before retrying

Published numeric limits are environment-specific and respect the response headers when present.

Generation processing

If try-on processing fails transiently, the platform may retry the job automatically. Do not assume a fixed number of processing attempts in client logic unless you have a separate public SLA.

When a job ends as failed, poll/webhook surfaces failed / generation.failed, and reserved credits are returned. See Credits.

Webhook delivery retries

Outbound webhooks to your URL are retried with backoff on network errors and most non-2xx responses. Certain client HTTP statuses stop delivery retries immediately (400, 401, 403, 404, 410, 501). Details: Webhooks and API Reference — Webhooks.

Client recommendations

1. Retry idempotent GETs with backoff on 503 / network errors.
2. Do not blindly retry POST /v1/generations without your own idempotency strategy — each accept reserves a credit.
3. For webhooks, process idempotently and return 2xx after durable accept.

Related

• API Reference