Errors and Limits

HTTP status codes, error response patterns, ingestion constraints, and retry guidance for the Numora Public API developer preview.

Scope

This page describes the error model and operational limits for the Numora Public API developer preview.

It combines two perspectives:

The public API response contract that external integrations should target.
The current ingestion constraints already enforced by the existing Numora app pipeline.

HTTP Status Codes

The public API uses conventional HTTP status codes.

200 OK: The request succeeded and returned a completed response body.
202 Accepted: The request was accepted for asynchronous processing.
400 Bad Request: The request was malformed or missing required input.
401 Unauthorized: The API key was missing or invalid.
403 Forbidden: The API key was valid but does not have permission to access the resource.
404 Not Found: The requested resource does not exist.
409 Conflict: The request conflicts with current resource state or idempotent expectations.
422 Unprocessable Entity: The payload shape was valid JSON, but the semantic values were invalid.
429 Too Many Requests: The client exceeded the current rate limit.
500, 502, 503, 504: A server-side or downstream provider error occurred.

Error Response Shape

Public API error responses should use a stable response body:

{
  "error": {
    "code": "file_too_large",
    "message": "file size exceeds the 30 MB limit",
    "request_id": "req_01jpy7v0j8w8f1sh3j2j1j0t7v"
  }
}

The request_id should also be returned in the x-request-id response header.

Common Error Codes

Common preview error codes include:

unauthorized
forbidden
invalid_payload
invalid_schema
unsupported_file_type
file_too_large
not_found
conflict
rate_limited
insufficient_credits
provider_error
internal_error

Current Ingestion Limits

The existing Numora app currently enforces the following upload and extraction constraints:

Maximum upload size: 30 MB
Supported upload formats: PDF, JPEG/JPG, PNG, TIFF, HEIC, HEIF, WEBP, GIF, BMP
Supported initial public schemas: invoice_v2, receipt_v1, contract_v1
Request correlation header: x-request-id

These values are based on the current implementation and may later vary by plan, environment, or endpoint.

Retry Guidance

Clients should handle retries based on status class:

Retry 429 and 5xx responses with exponential backoff and jitter.
Reuse the same external_id when retrying the same logical document creation.
Reuse the same execution_id only when replaying the same delivery callback attempt.
Do not blindly retry 4xx responses until the request is corrected.
For asynchronous document creation, prefer polling GET /v1/documents/{id} or consuming webhooks instead of resubmitting the same document repeatedly.

Notes for Current Numora Implementations

The current internal OCR pipeline already exposes a request correlation pattern using x-request-id, and enforces a 30 MB file limit on upload-oriented flows.

If public API routes are layered on top of the same ingestion pipeline, these constraints should remain documented until the implementation changes.

Errors and Limits

On this page