Skip to content
Compresr docs

API reference

Error codes

Compresr error envelope, every HTTP status code the API returns, and how to recover from each.

Every error the API generates uses the same flat envelope. The HTTP status code is the category; the code string is the specific failure mode, safe to switch on in client code.

Error envelope

Response
  • successboolean

    Always false on error responses.

  • errorstring

    Human-readable message safe to log or surface to operators. Wording may change.

  • codestring

    Stable machine-readable error code (e.g. authentication_error). Switch on this in client code.

  • detailstring | null

    Extra context when available, e.g. a pointer to the dashboard.

  • retry_afterinteger | null

    Seconds to wait before retrying. Set on rate-limit errors; mirrored in the Retry-After header.

  • fieldstring | null

    The request field that failed validation, when the error is attributable to one.

A concrete error response:

json

Two framework-level exceptions

Errors raised before a request reaches the API's handlers use FastAPI's default shape instead of the envelope: a missing required header or unparseable body returns 422 with {"detail": [{"type": "missing", "loc": ["header", "X-API-Key"], ...}]}, and an unknown route or method returns 404 with {"detail": "Not Found"}. Everything else uses the envelope above.

401 Unauthorized

The X-API-Key header is present but the key is malformed, unknown, revoked, or expired.

  • code: authentication_error: covers all key failures — the error and detail strings say which.
  • A request with no X-API-Key header at all returns 422 in the FastAPI shape (see callout above), not 401.
  • Recover by: issuing a fresh key in the dashboard and updating your secret store. See Authentication.

402 Payment Required

A billing operation failed at the payment layer.

  • code: insufficient_credits, budget_limit_reached, payment_failed.
  • Note: running out of usage balance on compression requests surfaces as 429 (see below), not 402.
  • Recover by: topping up or resolving the payment method in the dashboard.

403 Forbidden

The key authenticates but its scope doesn't permit this endpoint (for example, a demo-scoped key calling a compression endpoint).

  • code: scope_error.
  • Recover by: using a key with user or enterprise scope. Retrying with the same key returns the same error.

404 Not Found

  • code: not_found: the referenced resource (e.g. an API-key ID or model name in a path) doesn't exist or isn't visible to you.
  • An unknown URL path returns the FastAPI shape {"detail": "Not Found"} instead.
  • Recover by: checking the path and identifiers; do not retry unchanged.

422 Unprocessable Entity

The request was well-formed but one or more fields failed validation.

  • code: validation_error: typical causes are empty query, target_compression_ratio outside 0 to 200, more than 100 inputs items, or an unknown compression_model_name. When the failure is attributable to a single field, field names it.
  • Recover by: fixing the field indicated by field / error and retrying. Identical retries fail identically.

429 Too Many Requests

Your tier's per-minute or per-day quota is exhausted — or your usage balance / budget can't cover the request (the API pre-authorizes at worst-case cost).

  • code: rate_limit_exceeded: request, token, or spend budget exceeded. Rate-limit hits include retry_after and a Retry-After header; balance exhaustion does not clear on its own — check the error message to tell them apart.
  • Recover by: backing off with exponential delay that respects Retry-After (see Rate limits); if the message says usage limit, top up or raise your budget instead of retrying.

500 Internal Server Error

Unexpected server-side failure. Not your fault.

  • code: server_error.
  • Recover by: retrying once with a short delay. If it persists, check the status page and contact support.

503 Service Unavailable

An upstream dependency is unhealthy or the API is shedding load deliberately.

  • code: service_unavailable, connection_error, or circuit_open.
  • May include a Retry-After header.
  • Recover by: honouring Retry-After. Do not hammer the endpoint; that's what the circuit breaker is preventing.

504 Gateway Timeout

The request exceeded the server-side time budget.

  • code: timeout.
  • Recover by: retrying once; for very large contexts, consider splitting the input or using batch.

Best practices

  • Validate inputs client-side before making the request. Most 422 errors are catchable in your own code.
  • Retry only on 429, 500, 503, and 504. Never retry other 4xx errors; the response will be identical.
  • Use exponential backoff that respects Retry-After as a floor, not a ceiling.
  • Log code (stable) rather than error (human-readable, may change).