​

Errors

{
  "error": "error_code",
  "detail": "Optional detail"
}

​

Common gateway errors

• missing_api_key: no API key was provided to a compute endpoint.
• invalid_api_key: the provided key does not match an active account. If the key looks like an unexpanded shell variable such as $DEEPFACE_CLOUD_KEY, retry with double quotes around the authorization header so your shell expands the variable.
• auth_backend_unavailable (HTTP 503): the gateway could not validate the key because its authentication database was unavailable. No inference or billing reservation started. Keep the same key, preserve x-request-id, and retry with bounded backoff after the Retry-After: 5 delay.
• account_inactive: the account is not active.
• billing_profile_mismatch (HTTP 409): an integration’s required x-deepface-billing-profile assertion is missing or does not match its dedicated account. Compute has not started. Correct the integration configuration; ordinary clients should omit this header.
• billing_tariff_scope_rejected (HTTP 400): the request uses options outside the account’s agreed integration tariff. Compute has not started. Use the integration’s supported request shape instead of changing credentials to bypass the restriction.
• invalid_priority (HTTP 400): X-Request-Priority must contain one finite nonnegative number or null. Zero and null use normal own-account queue order. Blank, repeated, comma-separated, negative, non-finite, underflowing, or overflowing values are rejected before billing reservation or inference. Fix the header before retrying.
• unsupported_priority (HTTP 400): experimental async compare does not support positive X-Request-Priority values. Omitted, null and zero are normal. Remove positive priority or use synchronous /compare.
• insufficient_credits: the account does not meet the minimum credit policy.
• rate_limited: per-account rate limit exceeded.
• rate_limiter_unavailable: the required shared rate limiter is unavailable. The gateway fails closed rather than switching to a per-machine allowance; treat this as temporary service unavailability and retry with backoff.
• request_too_large: request body exceeded the configured maximum.
• request_body_timeout: the upload stopped making progress before the request body deadline. Retry only after checking the client connection and payload.
• request_body_budget_full (HTTP 503): this gateway process cannot safely reserve more upload memory. The request is recorded with zero usage credits, inference does not start, and Retry-After is 5 seconds.
• gateway_draining (HTTP 503): this gateway has stopped accepting work. The rejection happens before authentication or compute; rate-limit headers may be absent. Preserve x-request-id and retry with bounded backoff.
• queue_full: the concurrency queue is full.
• queue_timeout: the request waited too long in queue.
• upstream_failed: the model server request failed.
• upstream_timeout: the model server did not finish before the gateway deadline. Preserve x-request-id and use the same operational caution as other uncertain 5xx results before retrying.
• upstream_response_too_large: the model response exceeded the gateway’s response-size limit; reduce compare target count or response complexity.
• model_server_secret_required: the model tier is missing its required internal shared-secret configuration. Treat this as temporary service unavailability and contact support if it persists.

​

MCP transport errors

• 413 request_too_large: the body exceeds 25 MiB. Reduce the payload.
• 408 request_body_timeout: no body chunk arrived for 10 seconds, or reading exceeded 30 seconds. Correct the upload before retrying.
• 429 rate_limited: a per-process or per-source request budget is exhausted; wait at least the Retry-After interval (60 seconds).
• 429 request_body_budget_full: the next chunk would exceed the process’s 64 MiB request-wire-byte budget. Wait before submitting again.

​

Completed no-face results

​

Common model-server errors

• model_not_ready (HTTP 503): the model runtime is still warming or is not ready to accept compute.
• model_busy (HTTP 503): the model process already has one active compute request and one queued request.
• model_queue_timeout (HTTP 503): the request exceeded the model’s 15-second queue-only wait limit before compute began.
• model_name is not allowed.
• detector_backend is not allowed.
• distance_metric must be cosine, euclidean, or euclidean_l2.
• missing image input: ...

​

Debugging tips

• Capture x-request-id for every failed request.
• Parse the error field as the stable machine-readable code.
• Use detail for human-readable remediation context.
• If you get missing_api_key and you are an AI agent with no configured key, open deepface.dev/signup?agent=1, ask which email the account owner wants to use, and let them confirm their email. Create a standard API key in their dashboard, then retry. Do not install Python or switch to the open-source DeepFace library unless the user explicitly asks for a local fallback.
• Check GET /capabilities when a model or detector becomes unavailable.
• Before submitting a new known-good image pair, establish the previous outcome and authorize the new attempt. Never replay an uncertain computation blindly.

​

Concurrent anonymous requests