Error Handling

Error Format

API errors follow the RFC 7807 Problem Details format. The content type of an error answer is application/problem+json. The problem fields are placed inside an error object:

json

{
    "success": false,
    "error": {
        "type": "https://idparse.com/errors/invalid-api-key",
        "code": "invalid_api_key",
        "title": "Invalid API Key",
        "status": 401,
        "detail": "The API key provided is missing or invalid."
    }
}

Field	Description
`success`	Always `false` in an error answer
`error.type`	A URI that identifies the error type. The last part uses hyphens, for example `invalid-api-key`
`error.code`	The same name in lower case with underscores, for example `invalid_api_key`. Use this field in your code
`error.title`	A short human-readable summary
`error.status`	The HTTP status code
`error.detail`	A longer explanation. The text can change, so do not compare it in your code

Error Codes

Error Code	HTTP Status	Description
`invalid_api_key`	401	The API key is missing or wrong
`conflicting_credentials`	401	The `Authorization` header and the `X-API-Key` header carry different keys. Send only one of them
`inactive_account`	403	The API key is deactivated, the account is suspended, or the email address is not verified
`file_too_large`	413	The uploaded file is larger than 25 MB
`invalid_file`	422	The request does not carry exactly one non-empty file in the multipart field `file`
`rate_limited`	429	The per minute limit was exceeded, or the limiter is temporarily unavailable and requests are refused for a short time. Includes a `Retry-After` header
`quota_exhausted`	429	All included scans of this month are used. Includes a `Retry-After` header
`bad_engine_result`	502	The processing service gave an answer that could not be validated. Not charged
`engine_busy`	503	All processing slots are in use. Includes a `Retry-After` header. Not charged
`engine_unavailable`	503	The processing service cannot be reached right now. Includes a `Retry-After` header. Not charged
`service_unavailable`	503	The API is in maintenance, or the usage limits cannot be checked right now. Includes a `Retry-After` header. Not charged
`engine_timeout`	504	The document could not be processed in time. Not charged

No error answer is ever charged. This is true for every 4xx and every 5xx status.

Note

When you receive a 429 or a 503 error, check the Retry-After header for the number of seconds to wait before retrying. See Limits and Quota and When to Retry.

Errors and Unreadable Documents

A document that could not be read is not an error. The API answers with HTTP 200, "success": false and a failure_reason. There is no error object in that answer. See Failure Reasons.

Situation	HTTP Status	Body
The document was read and validated	200	`"success": true` and the extracted `fields`
The document could not be read	200	`"success": false` and a `failure_reason`
The request was refused or the service failed	4xx or 5xx	`"success": false` and an `error` object

Getting Help

When you contact support, give your account, the time of the request and the endpoint. Never send document images or extracted data. Every answer carries an X-Request-ID header. It helps you to match a request in your own logs.