Error Handling

The Dokai API uses conventional HTTP status codes and returns structured JSON error responses with machine-readable codes and human-readable messages.

Error response format

All errors follow a consistent structure. The suggestions array provides actionable steps to resolve the issue.

Error response

{
  "error": {
    "code": "invalid_file_type",
    "message": "The uploaded file is not a supported image format.",
    "type": "validation_error",
    "suggestions": [
      "Upload a JPEG, PNG, or WebP image",
      "Ensure the file is not corrupted",
      "Check that the Content-Type header matches the file"
    ]
  }
}

Error codes

Code	HTTP	Description
`invalid_api_key`	401	API key is missing, malformed, or revoked
`key_expired`	401	API key has been rotated or expired
`unauthorized`	401	Authentication failed
`forbidden`	403	Key does not have permission for this action
`not_found`	404	Requested resource does not exist
`result_expired`	410	Parse result has been purged after retention period
`validation_error`	422	Request parameters failed validation
`invalid_file_type`	422	File is not a supported image format (JPEG, PNG, WebP)
`file_too_large`	422	File exceeds the 10 MB size limit
`invalid_document_type`	422	Unrecognized document_type value
`invalid_document_brand`	422	Unrecognized document_brand value
`webhook_invalid_url`	422	webhook_url must use HTTPS or is malformed
`webhook_domain_not_allowed`	422	webhook_url domain is not in your allowed webhook domains
`quota_exceeded`	429	Monthly parse quota has been reached
`rate_limited`	429	Too many requests — slow down
`processing_failed`	500	Document could not be processed
`ocr_failed`	500	OCR engine failed to extract text
`internal_error`	500	Unexpected server error

Rate limiting

API responses include rate limit headers so you can track your current usage window.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Rate limit headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1741276800

Quota headers

Parse responses also include quota headers so you can monitor monthly usage without calling the usage endpoint.

Header	Description
`X-Quota-Limit`	Monthly parse quota
`X-Quota-Remaining`	Parses remaining this billing period
`X-Quota-Reset`	Unix timestamp when the billing period resets

Handling errors in code

# cURL outputs the response body directly.
# Check the HTTP status code with -w:
curl -s -w "\n%{http_code}" -X POST https://api.dokai.dev/v1/parse \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -F "file=@document.jpg"

# A non-200 status indicates an error.
# The response body contains the error JSON.

Validation endpoint

POST/v1/validate

Validate extracted data without submitting a document. Supports format validation for specific field types.

Supported types

Type	Description
`ic_number`	Malaysian IC number format and checksum validation
`mrz`	Passport MRZ (Machine Readable Zone) checksum validation

cURL

curl -X POST https://api.dokai.dev/v1/validate \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ic_number",
    "value": "880503-14-5234"
  }'