Error Codes

Complete error code reference for the Jonga OCR API. All errors follow a consistent response format with machine-readable error codes and human-readable messages.

Error Response Format

All error responses use the same envelope structure. The success field is always false, and the error object contains a machine-readable code and a human-readable message.

Error Responsejson

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of what went wrong"
  }
}

Error Codes Reference

CodeHTTPMessageWhen

UNAUTHORIZED401Missing or invalid API tokenNo or invalid Bearer token in Authorization header

TOKEN_DISABLED403This API token has been revokedToken isActive is set to false

TOKEN_SCOPE_DENIED403Token not authorized for this endpointToken scopes don't include the requested document type

TOKEN_EXPIRED403This API token has expiredToken is past its expiresAt date

IMAGE_MISSING400No image providedNo image field in multipart or JSON body

IMAGE_TOO_LARGE400Image exceeds 4MB limitUploaded file is larger than 4MB

IMAGE_INVALID_TYPE400Invalid image typeFile is not JPEG, PNG, or WebP

IMAGE_UNREADABLE422Document could not be readImage is too blurry, dark, or unclear to extract data

WRONG_DOCUMENT_TYPE422Image doesn't match expected document typeImage sent to wrong endpoint (e.g. passport to ID endpoint)

EXTRACTION_FAILED500Failed to extract document dataAI model response could not be parsed

RATE_LIMITED429Too many requestsRate limit exceeded for this token

VALIDATION_ERROR400Invalid request dataRequest body fails schema validation

INTERNAL_ERROR500An unexpected error occurredUnhandled server error

UNAUTHORIZED401

Missing or invalid API token

No or invalid Bearer token in Authorization header

TOKEN_DISABLED403

This API token has been revoked

Token isActive is set to false

TOKEN_SCOPE_DENIED403

Token not authorized for this endpoint

Token scopes don't include the requested document type

TOKEN_EXPIRED403

This API token has expired

Token is past its expiresAt date

IMAGE_MISSING400

No image provided

No image field in multipart or JSON body

IMAGE_TOO_LARGE400

Image exceeds 4MB limit

Uploaded file is larger than 4MB

IMAGE_INVALID_TYPE400

Invalid image type

File is not JPEG, PNG, or WebP

IMAGE_UNREADABLE422

Document could not be read

Image is too blurry, dark, or unclear to extract data

WRONG_DOCUMENT_TYPE422

Image doesn't match expected document type

Image sent to wrong endpoint (e.g. passport to ID endpoint)

EXTRACTION_FAILED500

Failed to extract document data

AI model response could not be parsed

RATE_LIMITED429

Too many requests

Rate limit exceeded for this token

VALIDATION_ERROR400

Invalid request data

Request body fails schema validation

INTERNAL_ERROR500

An unexpected error occurred

Unhandled server error

Troubleshooting

401UNAUTHORIZED

Make sure you include the Authorization header with the Bearer scheme.

Correct Authorization Headerbash

curl -X POST https://your-domain.vercel.app/api/v1/ocr/sa-id-smart-front \
  -H "Authorization: Bearer jonga_YOUR_TOKEN" \
  -F "image=@./id-front.jpg"

400IMAGE_MISSING

Ensure the image is sent either as a multipart form field named image or as a base64 string in the JSON body.

Multipart Uploadbash

# The field name must be "image"
curl -X POST https://your-domain.vercel.app/api/v1/ocr/sa-id-smart-front \
  -H "Authorization: Bearer jonga_YOUR_TOKEN" \
  -F "image=@./document.jpg"

400IMAGE_TOO_LARGE

Images must be under 4MB. Resize or compress the image before uploading. JPEG at 80% quality typically produces good results.

Compress with ImageMagickbash

# Resize and compress before uploading
convert input.jpg -resize 1500x1500 -quality 80 output.jpg

422WRONG_DOCUMENT_TYPE

Make sure the image matches the endpoint you are calling. For example, do not send a passport image to the /ocr/sa-id-smart-front endpoint.

Match Endpoint to Documentbash

# Passport image → use the passport endpoint
curl -X POST https://your-domain.vercel.app/api/v1/ocr/passport \
  -H "Authorization: Bearer jonga_YOUR_TOKEN" \
  -F "image=@./passport.jpg"

# Smart ID front → use the smart ID front endpoint
curl -X POST https://your-domain.vercel.app/api/v1/ocr/sa-id-smart-front \
  -H "Authorization: Bearer jonga_YOUR_TOKEN" \
  -F "image=@./id-front.jpg"

429RATE_LIMITED

You have exceeded the rate limit for your token. Check the X-RateLimit-Reset header to know when you can retry.

Check Rate Limit Headersbash

# Check remaining requests from response headers
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 0
# X-RateLimit-Reset: 1712345678

# Wait until the reset timestamp before retrying