Skip to content
Compresr docs
Edit this page

API reference

Error codes

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

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

Error envelope

Response
  • successboolean

    Always false on error responses.

  • errorobject
    • codestring

      Stable machine-readable error code (e.g. invalid_api_key).

    • messagestring

      Human-readable message safe to log or surface to operators.

400 Bad Request

The request body could not be parsed as JSON, or a required field was missing entirely.

  • code: invalid_request: body is not valid JSON or doesn't match the expected shape.
  • Recover by: fixing the request before retrying. Retries with the same body will fail identically.

401 Unauthorized

The X-API-Key header is missing, malformed, revoked, or expired.

  • code: missing_api_key: no X-API-Key header.
  • code: invalid_api_key: header present but the key doesn't exist or has been revoked.
  • code: expired_api_key: the key's expiry timestamp is in the past.
  • Recover by: issuing a fresh key in the dashboard and updating your secret store. See Authentication for rotation guidance.

403 Forbidden

The key authenticates but lacks access to the requested resource (for example, a feature gated to higher tiers).

  • code: forbidden: key is valid but not permitted to call this endpoint.
  • Recover by: upgrading your tier or contacting support. Retrying with the same key returns the same error.

422 Unprocessable Entity

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

  • code: validation_error: typical causes are empty query, target_compression_ratio outside 0 to 200, inputs array with more than 100 items, missing compression_model_name.
  • Recover by: fixing the field flagged in error.message and retrying.

429 Too Many Requests

Your tier's per-minute or per-day quota is exhausted.

  • code: rate_limit_exceeded: you've hit the request or token budget for your tier.
  • Response includes a Retry-After header with seconds to wait.
  • Recover by: backing off and retrying with exponential delay that respects Retry-After. See Handling 429 for the canonical pattern. If you hit 429 routinely under normal load, move to a higher tier.

500 Internal Server Error

Unexpected server-side failure. The error is not your fault.

  • code: internal_error: generic server failure.
  • Recover by: retrying once with a short delay. If the error persists across multiple requests, check the status page and contact support.

503 Service Unavailable

An upstream dependency is unhealthy and the circuit breaker is open. The API is shedding load deliberately to recover.

  • code: service_unavailable: upstream compression service circuit open.
  • Response includes a Retry-After header.
  • Recover by: honouring Retry-After. Do not hammer the endpoint; that's what the circuit is preventing.

Best practices

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