Saltar al contenido principal

​
Códigos de estado HTTP

CódigoDescripción
200Éxito.
400Petición incorrecta — descarga de documento fallida o URL inválida.
401No autorizado — API key inválida o faltante.
402Créditos insuficientes — recarga tu saldo para continuar.
404No encontrado — el deployment, entry o batch no existe.
422Error de validación — cuerpo de petición o formato de documento inválido.
503Servicio 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
}
CampoTipoDescripción
errorstringCódigo de error legible por máquina.
messagestringDescripción legible por humanos.
detailsobject o nullContexto 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")