Errores
Cada error dice qué pasó y, cuando es un dato, en qué campo. El formato es el estándar RFC 9457.
Los errores responden con Content-Type: application/problem+json (RFC 9457):
{
"type": "invalid_request",
"title": "La solicitud no es válida",
"status": 422,
"errors": [
{
"path": "lines.0.quantity",
"message": "Un decimal no negativo con hasta 6 decimales"
}
]
}typees estable: úsalo en tu código. Es un identificador en inglés que no cambia;title,detaily losmessagedeerrorsestán en español, son para personas y pueden cambiar.- En los errores de validación,
errorslista cada problema con la ruta del campo tal como la enviaste:lines.0.quantityes la cantidad de la primera línea.
Un campo desconocido nunca se ignora
Si envías un campo que no existe, no lo pasamos por alto: respondemos 422 con un error por cada campo desconocido, en su ruta.
{
"type": "invalid_request",
"title": "La solicitud no es válida",
"status": 422,
"errors": [
{ "path": "metdata", "message": "Campo desconocido" },
{ "path": "lines.0.auxiliary_cod", "message": "Campo desconocido" }
]
}Ignorarlo sería peor: creerías que aceptamos un dato que nunca llegó al comprobante. Lo mismo con un campo que no te corresponde decidir, como environment (lo decide tu clave) o establishment al corregir (el número ya está tomado).
Tipos
type | Estado | Qué significa | Qué hacer |
|---|---|---|---|
invalid_request | 422 | Un dato no es válido o rompe una regla del SRI | Corrige el campo de errors y reintenta |
unauthorized | 401 | Falta la clave API, no es válida o fue revocada | Revisa el encabezado Authorization |
key_not_permitted | 403 | El permiso de tu clave no alcanza para esta operación: el detalle dice cuál hace falta | Usa una clave con ese permiso |
forbidden | 403 | Solo una persona con rol owner o admin puede hacerlo desde la plataforma, como crear claves | Hazlo desde la plataforma |
not_found | 404 | No existe en tu organización y ambiente | Revisa el id y la clave que usas |
conflict | 409 | El Idempotency-Key ya se usó con otra venta, o el estado no permite la acción | Usa otra clave o revisa el estado |
not_ready | 409 | Aún no puedes hacerlo: falta entidad, numeración o certificado, o el comprobante no está autorizado | Completa lo que dice detail |
plan_limit | 402 | Un negocio en vivo no puede emitir: su plan con cuota no permite otro comprobante de Producción este mes porque no tiene precio de adicionales o el adicional superaría el tope que pusiste (Scale nunca lo rechaza por cuota), no tiene plan (o lo canceló), no ha completado su primer pago o un cobro está vencido. También rechaza corregir o renumerar un comprobante de Pruebas o Producción. No se numeró nada | Sube de plan, elige uno y paga, o paga el cobro vencido, y reintenta con la misma Idempotency-Key |
authority_unavailable | 503 | El SRI no responde y no tenemos una respuesta guardada | Reintenta en unos minutos |
internal | 500 | Un error nuestro; queda registrado | Reintenta con la misma Idempotency-Key |
El portal del receptor tiene tres más, para su código de acceso: invalid_code (401, con attempts_left), code_expired (401) y too_many_attempts (429).
Las reglas del SRI son errores de validación
Muchas reglas no son de formato sino del SRI, y las revisamos antes de numerar, para que el SRI no te devuelva el comprobante después:
- Una factura de más de USD 50 no puede ir a consumidor final: el comprador debe identificarse.
- Cada línea lleva exactamente un IVA.
- La información adicional cabe en los 15 campos que permite el comprobante.
- En una guía de remisión, el traslado no puede empezar antes de emitirla.
Un comprobante rechazado por estas reglas no consume número.