Error handling - Matil Documentation

HTTP status codes

Status	Description
`200`	Success.
`400`	Bad request — document download failed or invalid URL.
`401`	Unauthorized — invalid or missing API key.
`402`	Insufficient credits — top up your balance to continue.
`404`	Not found — deployment, entry, or batch doesn’t exist.
`422`	Validation error — invalid request body or document format.
`503`	Service temporarily unavailable due to high load. Retry with exponential backoff.

Error response format

{
  "error": "DEPLOYMENT_NOT_FOUND",
  "message": "Deployment not found",
  "details": null
}

Field	Type	Description
`error`	string	Machine-readable error code.
`message`	string	Human-readable description.
`details`	object or null	Additional context when available.

Processing errors vs. API errors

API errors (4xx): the request itself failed. No document was processed.
Processing errors (in the errors field of a 200 response): the document was processed but some fields couldn’t be extracted or validated.

A response with status: "completed_with_errors" is still a 200 OK:

{
  "data": {"invoice_number": "INV-001", "total": null},
  "errors": [{"path": "/total", "message": "Required field missing", "code": "REQUIRED_FIELD"}],
  "status": "completed_with_errors"
}

Retry strategy

For 503 (high load) responses, implement exponential backoff:

import time
import requests

def process_with_retry(deployment_id, documents, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            f"https://api.matil.ai/v3/deployments/{deployment_id}",
            headers={"x-api-key": api_key},
            json={"documents": documents}
        )
        if response.status_code == 503:
            time.sleep(2 ** attempt)
            continue
        return response.json()
    raise Exception("Max retries exceeded")