Docs

Home All sections Swagger

Errors

Every error code the API returns, what causes it, and how to fix it.

Last updated June 3, 2026

Using the Python SDK?

The SDK turns every error here into a typed exception. The full mapping (which status code becomes which exception) is in Errors and exceptions.

Every error response has the same shape:

{
  "error": {
    "code": "scope_required",
    "message": "This endpoint requires the submissions:write scope.",
    "details": {},
    "request_id": "..."
  }
}

code is stable across versions. Use it in your error handling. message is human-readable and may change over time. details is a per-error dict (e.g. it carries field for validation errors, retry_after for rate-limit errors, used/limit for quota errors). request_id matches the X-Request-Id response header, quote it in support emails so we can find the request in our logs.

400: Bad request

Code Cause Fix
invalid_parameter A query string parameter is malformed. Read the field value and the message; fix the input.
invalid_body The JSON body did not parse or did not match schema. Validate the JSON before sending. Check field types.

422: Request did not validate

Code Cause Fix
validation_failed A submission's parameters are inconsistent. Read the message for the specific reason.
idempotency_key_mismatch The same Idempotency-Key was reused with a different body. Generate a fresh UUID for each distinct submission.

401: Not authenticated

Code Cause Fix
missing_credentials No Authorization header. Send the header with Bearer <key>.
invalid_credentials The key does not exist, was revoked, or has expired. Check the key. Rotate or create a new one.
account_disabled The owning account is disabled or unverified. Sign in to the website and resolve the warning.

402: Payment required

Code Cause Fix
insufficient_credits Your free + paid credit balance is at or below the negative-balance cap (default $1). Top up credits. See Credits.

403: Not authorised

Code Cause Fix
scope_required The key does not have the scope this endpoint needs. Edit the key's scopes (Editing the scopes on an existing key) or use a different key.
tier_limit_exceeded A submission parameter is above your tier's cap (e.g. num_generations, num_genes). Reduce the parameter, or upgrade your tier. See Rate limits and quotas.
forbidden The action is not allowed on this resource. Check ownership or share state.

404: Not found

Code Cause Fix
not_found The id does not exist or does not belong to your account. Check the id and that the resource is yours.

409: Conflict

Code Cause Fix
state_conflict The submission cannot move from its current state to the requested one. Check the current status first.
duplicate_resource A resource with this name already exists. Pick a different name.
idempotency_key_in_progress A request with the same Idempotency-Key is still being processed. Wait briefly and retry the same request.

429: Too many requests

Code Cause Fix
rate_limited Per-minute rate limit hit (default 60 req/min). Honor Retry-After, then retry. See Rate limits and quotas.
capacity_exceeded One of: daily-quota cap, concurrent-submissions cap, or platform queue at capacity. Read details.reason to tell which. Wait for in-flight runs to finish, retry tomorrow, or upgrade the tier.
too_many_active_api_requests You already have the maximum number of API submissions in flight (default 5). Wait for one to finish before creating another.

5xx: Server-side problems

Code Cause Fix
internal_error Something on our side broke. We log every occurrence. Retry with backoff. If it persists, contact support with the request id from the response.
service_unavailable The platform is temporarily over-loaded or in maintenance. Retry after the period in Retry-After.

How to read the request id

Every response includes an X-Request-Id header. Include it in any support email; it lets us look up the exact request in our logs.

Thanks for the feedback!