Errors

Understanding how the Knowhere API communicates errors helps you build reliable integrations. Errors can surface in two ways — as HTTP error responses from the API, or as job failures reported asynchronously when a parsing job fails.

HTTP Errors

The API uses standard HTTP status codes with canonical error codes:

Client Errors (4xx)

HTTP	Error Code	Description	Retryable
400	INVALID_ARGUMENT	Invalid request format or content	No
400	FAILED_PRECONDITION	System state prevents the operation	No
401	UNAUTHENTICATED	Missing or invalid API key	No
402	PAYMENT_REQUIRED	Insufficient credits	No
403	PERMISSION_DENIED	API key lacks required permission	No
404	NOT_FOUND	Resource does not exist	No
409	ALREADY_EXISTS	Resource already exists	No
409	ABORTED	Concurrency conflict	Yes
429	RESOURCE_EXHAUSTED	Rate limit or quota exceeded	Conditional

Current 429 Semantics

In the current API implementation, polling RPM limits, job-creation RPM limits, daily quota checks, and concurrent active-job caps all surface as RESOURCE_EXHAUSTED with details.reason = "RATE_LIMIT_EXCEEDED".

Use details.period to tell them apart:

• minute: per-minute rate limit
• day: daily job-creation quota
• concurrent: active-job concurrency cap

The Retry-After response header is the canonical retry hint.

Server Errors (5xx)

HTTP	Error Code	Description	Retryable
500	INTERNAL_ERROR	Internal server error	Yes
500	UNKNOWN	Unexpected error (fallback)	Yes
503	UNAVAILABLE	Service temporarily unavailable	Yes
504	DEADLINE_EXCEEDED	Request timed out	Yes

Server errors are generally safe to retry with exponential backoff. The SDK retries these automatically.

Job Failure Errors

Because Knowhere processes documents asynchronously, some errors only surface when a job reaches the failed state. These are reported in the error object on the job response — not as HTTP errors.

Error Shape

All HTTP error responses follow a consistent JSON envelope:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Job not found",
    "request_id": "req_abc123def456",
    "details": {
      "resource": "Job",
      "id": "job_xyz789"
    }
  }
}

Field	Type	Description
code	string	Machine-readable error code (see tables above)
message	string	Human-readable, user-safe description
request_id	string	Unique identifier for this request or job
details	object	Additional structured context (varies by error type)

note

The message field always contains a user-safe description. Internal debugging details are never exposed in the response — they are only captured in server logs.

Common Detail Schemas

Different error codes provide different details structures:

Validation errors (INVALID_ARGUMENT):

{
  "violations": [
    { "field": "file", "description": "Exceeds 100MB limit" }
  ]
}

Rate limit errors (RESOURCE_EXHAUSTED):

{
  "reason": "RATE_LIMIT_EXCEEDED",
  "retry_after": 15,
  "limit": 200,
  "period": "minute"
}

Not found errors (NOT_FOUND):

{
  "resource": "Job",
  "id": "job_abc123"
}

Insufficient credits (PAYMENT_REQUIRED):

{
  "required_credits": 10.0
}

Request ID

Every API response includes a request_id in the error body. When contacting support about a specific request or job, always include this ID — it lets us trace the exact request through our systems.

Retry Strategy

What to Retry

Category	Retry?	Strategy
UNAVAILABLE (503)	Yes	Exponential backoff
DEADLINE_EXCEEDED (504)	Yes	Exponential backoff
INTERNAL_ERROR (500)	Yes	Exponential backoff
RESOURCE_EXHAUSTED (429)	Conditional	Wait details.retry_after seconds
ABORTED (409)	Yes	Retry immediately
All other 4xx	No	Fix the request first

Built-in SDK Retries

The Python SDK automatically retries connection errors, 429, and ≥500 errors with exponential backoff:

client = knowhere.Knowhere(
    api_key="sk_...",
    max_retries=3,  # default is 5
)

Getting Help

If you encounter persistent errors:

1. Note the request_id from the error response
2. Check the status page for outages
3. Contact support at team@knowhereto.ai

Include the full error response (without your API key) and when the error occurred.