Skip to main content

​
HTTP status codes

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

​
Error response format

{
  "error": "DEPLOYMENT_NOT_FOUND",
  "message": "Deployment not found",
  "details": null
}
FieldTypeDescription
errorstringMachine-readable error code.
messagestringHuman-readable description.
detailsobject or nullAdditional 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")