Errors & Retries | FreeAIOCR

These shared guides apply to Image to Text and Image to Table. Check each API reference for its supported inputs, formats and specific errors.

Error Responses

Example JSON error response:

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "error": {
    "code": "insufficient_balance",
    "message": "Recognition did not complete",
    "required_reservation_usd": "0.011288000"
  }
}

HTTP Status Codes

HTTP	error.code
400	invalid_request, invalid_idempotency_key, invalid_image
401	unauthorized
402	insufficient_balance
403	account_unavailable
405	invalid_request
409	idempotency_conflict, request_in_progress
413	image_too_large, input_limit_exceeded
415	unsupported_media_type
422	recognition_blocked
429	rate_limit_exceeded, concurrency_limit_exceeded
502	recognition_failed, output_truncated, empty_result, invalid_usage
503	service_unavailable, settlement_pending, export_failed
504	request_timeout

HTTP	Cause	What to do
400 / 413 / 415	Invalid request, image size or media type	Correct the upload or reduce its size
405	Wrong HTTP method	Use POST
401	Missing or invalid API key	Check your Bearer API key
403	Account unavailable	Verify your account or resolve its restriction
402	Insufficient available balance	Top up; check error.required_reservation_usd and balance reservations
409	Idempotency conflict or operation still processing	For request_in_progress, keep the original key and image and retry after waiting; for a conflict, correct the operation ID
429	Request rate or concurrency limit	Wait according to Retry-After
422 / confirmed 502	Confirmed recognition failure	No recognition charge; inspect the error before deciding whether to start again
503 / 504 / uncertain outcome	Service, settlement or timeout uncertainty	Do not assume no charge; retry with the same Idempotency-Key and original image

Error responses are JSON containing request_id, error.code, and error.message. Every response uses Cache-Control: no-store. Recognition is not streamed: successful responses use the requested format, while errors remain JSON. Keep X-Request-Id when contacting support.

Idempotency

Idempotency-Key is your operation ID: 16–128 ASCII letters, digits or . _ : -. Choose a new unique ID for a new image; reuse it with identical original bytes and MIME for retries. It is account-scoped, even when switching API keys. Within 24 hours of acceptance, a completed retry returns the original request_id, result and charge with Idempotency-Replayed: true; it does not generate or charge again.

Use a different Idempotency-Key for each new operation or endpoint. Reusing it across Image to Text and Image to Table returns 409 idempotency_conflict. Switching formats within the same operation reuses the original key and image.

Retry Strategy

For network errors, request_in_progress or settlement_pending, keep the same ID and image, wait Retry-After seconds and retry. Do not create another operation while settlement is uncertain. Stored terminal failures replay the same error; use a new ID only when intentionally starting again after confirming failure. After 24 hours an ID may start a newly charged operation; unresolved recovery still blocks reuse.

Billing Safety

A confirmed recognition failure is not charged, but a lost response or settlement_pending may already be settled or retain a reservation. Never use a new Idempotency-Key while the original outcome is uncertain; retry with the same key and image, and keep X-Request-Id for support.