Errors and limits

Error response format

When a request fails, NDI returns a typed error:

{
  "error": {
    "code": "unsupported_file_type",
    "message": "File type .xlsx not supported by parse; use /v1/classify for spreadsheets",
    "detail": null,
    "retryable": false,
    "request_id": "req-01j9..."
  }
}

Fields:

code — Machine-readable identifier. Treat it as an open enum so new codes remain compatible.
message — Human-readable explanation.
detail — Operation-specific context (e.g., validation field errors). null when the code carries no additional payload.
retryable — Whether retrying the identical request could succeed.
request_id — Per-request correlation id; matches the X-Request-Id response header.

Error codes

`invalid_request`

Missing required field, wrong type, value out of range, or extra field on a strict model. HTTP: 422

`unsupported_file_type`

File extension not supported by the requested operation. HTTP: 422

`file_too_large`

Uploaded file exceeds the size limit for POST /v1/uploads. HTTP: 413

`unauthorized`

API key missing, invalid, or revoked. HTTP: 401

`access_denied`

Operation not allowed for this key (e.g., session belongs to a different key). HTTP: 403

`workspace_not_found`

Workspace does not exist (or the key cannot see it). HTTP: 404

`file_not_found`

File or output does not exist. HTTP: 404

`job_not_found`

Job does not exist for this key. HTTP: 404

`session_not_found`

Intelligent-search session ID does not exist in this workspace, or it is the ID of a follow-up job rather than the thread root. HTTP: 404

`kg_not_built`

Knowledge-graph tool called on a workspace with no built graph. HTTP: 409

`kg_build_in_progress`

A knowledge-graph build is already running for this workspace. HTTP: 409

`workspace_deleting`

Operation attempted on a workspace that is currently being deleted. HTTP: 409

`session_busy`

A deep-search session is still answering a previous turn. HTTP: 409

`rate_limited`

Per-key requests-per-minute limit hit. HTTP: 429

`concurrency_limit_reached`

Per-key concurrent-jobs cap hit. HTTP: 429

`corrupt_file`

File could not be processed because it is corrupt or not the format its extension claims. HTTP: Used in job failure error.code, not as an HTTP status. The job status is "failed".

`internal_error`

Unexpected server error. The response marks this code as retryable. HTTP: 500

HTTP status codes

Code	Meaning
200	Success; result is inline (job completed within `wait_seconds`)
202	Accepted; job queued or still running; poll `GET /v1/jobs/{job_id}`
401	Unauthorized — API key missing or invalid
403	Forbidden — access denied
404	Not found
409	Conflict — resource state prevents the operation
413	Payload too large — file exceeds size limit
422	Unprocessable entity — request schema validation failed
429	Rate limited — RPM cap (`rate_limited`) or concurrent-jobs cap (`concurrency_limit_reached`)
500	Internal error — retryable with idempotency key

Rate limits

Per API key:

Concurrent jobs: Configurable per key; when the cap is hit, new job-creating requests return 429 concurrency_limit_reached.
RPM (requests per minute): Enforced per key via Redis (no-ops when Redis is unavailable in local dev). When the cap is hit, requests return 429 rate_limited.

Retry strategy

For 429 or 5xx errors:

Include Idempotency-Key to ensure replay is safe.
Wait with exponential backoff: wait = min(2^attempt, 60) seconds.
Retry up to 5 times before giving up.

`wait_seconds` timeout

When a job does not complete within ?wait_seconds= (max 300), the endpoint returns 202 (not 408). The job continues running; poll it.

Getting started

SDKs and agents

Concepts

Error response format

Error codes

`invalid_request`

`unsupported_file_type`

`file_too_large`

`unauthorized`

`access_denied`

`workspace_not_found`

`file_not_found`

`job_not_found`

`session_not_found`

`kg_not_built`

`kg_build_in_progress`

`workspace_deleting`

`session_busy`

`rate_limited`

`concurrency_limit_reached`

`corrupt_file`

`internal_error`

HTTP status codes

Rate limits

Retry strategy

`wait_seconds` timeout

​Error response format

​Error codes

​invalid_request

​unsupported_file_type

​file_too_large

​unauthorized

​access_denied

​workspace_not_found

​file_not_found

​job_not_found

​session_not_found

​kg_not_built

​kg_build_in_progress

​workspace_deleting

​session_busy

​rate_limited

​concurrency_limit_reached

​corrupt_file

​internal_error

​HTTP status codes

​Rate limits

​Retry strategy

​wait_seconds timeout

Error response format

Error codes

`invalid_request`

`unsupported_file_type`

`file_too_large`

`unauthorized`

`access_denied`

`workspace_not_found`

`file_not_found`

`job_not_found`

`session_not_found`

`kg_not_built`

`kg_build_in_progress`

`workspace_deleting`

`session_busy`

`rate_limited`

`concurrency_limit_reached`

`corrupt_file`

`internal_error`

HTTP status codes

Rate limits

Retry strategy

`wait_seconds` timeout