Errors - Krun

Every error has the same JSON shape, with a stable machine-readable code:

{
  "error": {
    "code": "INVALID_OPTIONS",
    "message": "questions.department: 1 options given; between 2 and 64 are required",
    "request_id": "req_0b7f7c5e9a3d4a8c9f1e2d3c4b5a6978"
  }
}

Field	Description
`code`	Stable error code. Branch on this, not on `message`.
`message`	Human-readable explanation. The wording can change.
`request_id`	Id of the failed request. Include it when you contact support.

Error codes

Code	HTTP	Meaning	Retry
`INVALID_REQUEST`	400	The request is malformed: missing or unknown fields, wrong types, empty context, too many questions, duplicate ids.	No
`INVALID_OPTIONS`	400	A question’s options are invalid, for example fewer than 2 or more than 64.	No
`UNAUTHORIZED`	401	Missing, invalid or revoked API key.	No
`NOT_FOUND`	404	Unknown path, or feedback for a `request_id` your project never decided.	No
`PAYLOAD_TOO_LARGE`	413	The request body is larger than 256 KiB.	No
`RATE_LIMITED`	429	The API key’s per-minute rate limit was reached.	After `Retry-After`
`QUOTA_EXCEEDED`	429	The project’s monthly quota is exhausted.	No
`INTERNAL_ERROR`	500	Unexpected error in the API.	No
`INFERENCE_FAILED`	502	The model backend failed to produce a valid answer.	Yes, with backoff
`UPSTREAM_UNAVAILABLE`	503	The model backend is temporarily unavailable. Sent with `Retry-After`.	Yes, with backoff
`UPSTREAM_TIMEOUT`	504	The model backend did not answer within the API’s deadline, for example during a slow cold start.	Yes, with backoff

A request with a wrong HTTP method keeps its 405 status and uses the INVALID_REQUEST code. Invalid requests (400 and 413) are rejected before any inference runs, and don’t count toward quotas.

Retrying

Retry 502, 503, 504 and connection errors with exponential backoff and jitter. Honor Retry-After when present. Keep retries few: the API already retries its model backend.
For 429 RATE_LIMITED, wait for the number of seconds in Retry-After before sending more requests.
Don’t retry 400, 401, 404, 413 or 429 QUOTA_EXCEEDED automatically: the same request will fail again.
500 INTERNAL_ERROR is not retried by the SDK. If it persists, contact support with the request id.

See Production best practices.

Errors in the Python SDK

The Python SDK raises one exception class per code, and retries 502, 503 and 504 once by default:

Code	Exception
`INVALID_REQUEST`, `INVALID_OPTIONS`, `PAYLOAD_TOO_LARGE`	`InvalidRequestError`
`UNAUTHORIZED`	`AuthenticationError`
`NOT_FOUND`	`NotFoundError`
`RATE_LIMITED`	`RateLimitError`
`QUOTA_EXCEEDED`	`QuotaExceededError`
`INFERENCE_FAILED`	`InferenceFailedError`
`UPSTREAM_UNAVAILABLE`	`ServiceUnavailableError`
`UPSTREAM_TIMEOUT`	`UpstreamTimeoutError`
`INTERNAL_ERROR`	`InternalServerError`

All of them inherit from krun.APIError and krun.KrunError, and carry error_code, status_code, message and request_id. See Python SDK errors.

⌘I