Manejo de errores - Matil Documentation

Códigos de estado HTTP

Código	Descripción
`200`	Éxito.
`400`	Petición incorrecta — descarga de documento fallida o URL inválida.
`401`	No autorizado — API key inválida o faltante.
`402`	Créditos insuficientes — recarga tu saldo para continuar.
`404`	No encontrado — el deployment, entry o batch no existe.
`422`	Error de validación — cuerpo de petición o formato de documento inválido.
`503`	Servicio temporalmente no disponible por alta carga. Reintenta con backoff exponencial.

Formato de respuesta de error

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

Campo	Tipo	Descripción
`error`	string	Código de error legible por máquina.
`message`	string	Descripción legible por humanos.
`details`	object o null	Contexto adicional cuando esté disponible.

Errores de procesamiento vs. errores de API

Errores de API (4xx): la petición falló. No se procesó ningún documento.
Errores de procesamiento (en el campo errors de una respuesta 200): el documento se procesó pero algunos campos no pudieron extraerse o validarse.

Una respuesta con status: "completed_with_errors" sigue siendo un 200 OK:

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

Estrategia de reintentos

Para respuestas 503 (alta carga), implementa backoff exponencial:

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("Máximo de reintentos excedido")