Error codes
The API uses standard HTTP codes. These are the ones the public surface can return.
| Code | Meaning |
|---|---|
401 | API key missing, malformed, invalid, revoked or expired. |
402 | Insufficient credit balance. |
403 | The key lacks the required scope. |
404 | Resource not found (or belongs to another tenant: not distinguished). |
409 | Conflict: the SKU already exists · batch not cancelable · operation with that Idempotency-Key in flight. |
413 | The body exceeds the 2 MB limit (catalog import and image upload). |
415 | The uploaded file is not what `presign` declared: its binary signature does not match the `mime` (or it is a format we do not accept, such as SVG). The object is discarded; start over with the right file. |
422 | Invalid payload (incl. empty batch or over 500 products) · Idempotency-Key reused with a different payload or endpoint. |
428 | Missing the required Idempotency-Key (POST /v1/batches). |
429 | Rate limit (retry after Retry-After) or daily AI spend cap (no Retry-After). |
502 | The image provider rejected the request (AI photo sessions): not charged. Check the references and retry. |
503 | Service paused (maintenance, AI off, or public API disabled): nothing was charged. |