Error Handling

The Parsify API uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate a server error.

Status Code Summary

Error Shapes

400 Bad Request

Returned when the request body fails validation. The response is a JSON object where each key is a field name and each value is a list of error messages.

{
  "file": ["No file was submitted."],
  "create_job": ["Must be a valid boolean."]
}

Field-level errors make it straightforward to map validation failures back to specific input fields in your application.

401 Unauthorized

Returned when the request is missing an API key or the key is invalid.

{
  "detail": "Authentication credentials were not provided."
}

Verify that you are including a valid API key in the X-API-Key header. See Authentication for details.

403 Forbidden

Returned when your API key is valid but lacks the required scope for the endpoint.

{
  "detail": "You do not have permission to perform this action."
}

Check that your API key has the necessary scopes. See Auth Scopes for a full list.

404 Not Found

Returned when the requested resource does not exist, or does not belong to your organization.

{
  "detail": "Not found."
}

429 Too Many Requests

Returned when you exceed the rate limit for your organization.

{
  "detail": "Request was throttled. Expected available in 60 seconds."
}

Back off and retry after the indicated time. Implement exponential backoff in production integrations.

Handling Errors

We recommend the following practices when handling errors from the Parsify API:

• Check the status code first. Use the HTTP status code to determine the category of error before parsing the response body.
• Parse field-level errors for 400 responses. Iterate over the keys in the response object to surface specific validation messages to your users.
• Implement retries for 429 and 5xx errors. Use exponential backoff with jitter to avoid thundering herd problems.
• Do not retry 401 or 403 errors. These indicate a configuration issue with your API key that must be resolved before retrying.