Reference

Errors

HTTP and gRPC error codes, retry guidance, and idempotency key usage.

HTTP Error Codes

Status	Meaning	Retry?
`400`	Invalid request body, vector payload, or field value	No — fix the request
`401`	Missing or invalid API key	No — check your key
`403`	API key scope does not permit this operation	No — use a key with the correct scope
`404`	Endpoint not found	No — check the URL
`405`	Wrong HTTP method for this endpoint	No — use the correct method
`409`	Idempotency key conflict	Usually no — a previous request with this key already succeeded
`429`	Rate limit exceeded	Yes — exponential backoff
`500`	Internal server error	Maybe — retry once, then contact support
`503`	Service temporarily unavailable	Yes — retry with backoff

gRPC Status Codes

If you use the Python SDK, gRPC errors are automatically mapped to typed exceptions:

gRPC Code	SDK Exception	Retry?
`INVALID_ARGUMENT`	`InvalidArgumentError`	No
`UNAUTHENTICATED`	`AuthenticationError`	No
`PERMISSION_DENIED`	`PermissionDeniedError`	No
`NOT_FOUND`	`NotFoundError`	No
`RESOURCE_EXHAUSTED`	`QuotaExceededError`	With backoff
`DEADLINE_EXCEEDED`	`DeadlineExceededError`	Yes
`UNAVAILABLE`	`ServiceUnavailableError`	Yes
`INTERNAL`	`InternalServerError`	Maybe

Retry Guidance

Retry 429, 503, UNAVAILABLE, and DEADLINE_EXCEEDED with bounded exponential backoff.
Do not retry 400, 401, 403, or 404 — these indicate a problem with your request or credentials.
Always send x-idempotency-key on write operations so retries are safe.
The Python SDK handles retries automatically when configured with a RetryPolicy.

Idempotency

Include an x-idempotency-key header on all mutating requests (upsert, update, delete). If the same idempotency key is sent twice, the gateway returns the original response without re-executing the operation. This makes retries safe even for write operations.