Skip to main content

Errors & Limits

Primex returns standard HTTP status codes. On the money side, failed requests aren't billed; successfully delivered usage is metered. If usable output was delivered before a later stream error, that delivered usage may be charged. See Billing & Credits for the full metering and refund model.

Status codes​

StatusMeaningChargedWhat to do
200SuccessMeasured usage—
4xxClient error: malformed request, invalid or expired key, unknown or unavailable model$0Fix the request; do not blind-retry
499Client aborted the request (CLIENT_ABORT): you closed the connection or cancelled a stream$0Expected on cancellation
502Upstream returned an invalid/unparseable response$0Retry with backoff
503A safety precondition (rate limit, concurrency, reservation, or balance read) could not be established$0Retry with backoff; these paths fail closed on purpose

Model routing errors surface as model_not_found (unknown ID) or model_not_available (known but not currently serveable). Refresh model discovery rather than caching a model list forever. See Models and Live Catalogue.

Rate & concurrency limits​

Primex bounds load to protect every account:

  • Requests per minute per key and across all keys on the account.
  • Concurrency: how many requests run at once. Pay-as-you-go keys share a small per-account concurrency budget across all their keys; subscription plans use their plan's concurrency limit.
  • Per-key monthly spend caps: an optional UTC-calendar-month safety guard you set per key. Because billing is post-paid, one already-admitted request can finish slightly above the cap; it is a guard, not a hard prepaid ceiling.

Rate, concurrency, and monthly spend-cap limits return 429; exhausted credit returns 402. Rate-limit responses expose X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset where applicable. Back off on temporary limits and honor Retry-After when present. A monthly spend-cap rejection needs a cap change or the next UTC month; an exhausted balance needs a top-up.

Retries & idempotency​

  • A request that fails before provider work can be retried without a supplier charge. If the connection drops after dispatch, the supplier outcome may be unknown; check the request ID and usage before starting a new paid operation.
  • First-party Primex surfaces (e.g. Primex Chat) send an X-Primex-Operation-ID. Direct image generation, image edits, and video generation currently accept requests without it, but clients should send one unique ID per logical generation and reuse that exact ID on an uncertain retry. The planned shared-output mode will require the header for those direct media routes and reject a repeated submitted ID with 409 duplicate_operation; it does not replay the old result. Do not silently create a new ID after a timeout.
  • Fix invalid requests before retrying. For 429, wait for the retry window; for 409 duplicate_operation, inspect the original operation rather than submitting another paid job.

Fund protection recap​

Post-paid metering, broken-stream detection, a meter-integrity circuit, and admin refunds mean you are not charged for work you did not successfully receive. The customer-facing summary of these protections lives in Usage; the mechanics are in Billing & Credits.