Errors

IdenticAPI returns structured error responses with a machine-readable code, a human-readable message, and a request ID for support and debugging.

Error response format

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry later.",
    "request_id": "req_abc123"
  }
}

Every error response includes an X-Request-Id header matching error.request_id. Include this ID when contacting support.

Error codes

Code	HTTP status	Description
`invalid_api_key`	401	The API key is missing, malformed, or does not match any active key.
`revoked_api_key`	401	The API key has been revoked and can no longer be used.
`invalid_request`	400	The request body is invalid JSON or fails schema validation.
`payload_too_large`	400	The request payload exceeds the maximum allowed size.
`rate_limit_exceeded`	429	Too many requests in the current rate-limit window. Retry after a short delay.
`quota_exceeded`	429	Monthly usage quota for your plan has been exhausted.
`feature_unavailable`	403	The requested feature is not available on your current plan.
`provider_processing_failure`	502	An upstream processing provider failed. Retry the request.
`internal_error`	500	An unexpected server error occurred.
`unauthorized`	401	Authentication is required but was not provided.
`not_found`	404	The requested resource or endpoint was not found.

Common scenarios

Authentication failures (401)

Send your API key in the Authorization: Bearer YOUR_API_KEY header. Keys must use the idapi_test_ or idapi_live_ prefix. See Authentication for details.

Validation errors (400)

A invalid_request error usually means a required field is missing, a string exceeds the maximum length (32,000 characters for text fields), or the JSON body is malformed.

Rate limits and quotas (429)

rate_limit_exceeded — per-minute request limit for your plan. See Rate Limits.
quota_exceeded — monthly usage unit limit reached. See Usage & Billing.

Retry guidance

429 (rate limit / quota) — wait and retry with exponential backoff for rate limits; upgrade your plan for quota exhaustion.
502 (provider failure) — safe to retry; the detector may fall back to pattern matching if an AI provider is unavailable.
500 (internal error) — retry once; contact support with the request ID if the error persists.