Errores

Los errores responden con Content-Type: application/problem+json (RFC 9457):

{
  "type": "invalid_request",
  "title": "The request is not valid",
  "status": 422,
  "errors": [
    {
      "path": "lines.0.quantity",
      "code": "decimal_format",
      "message": "Use a non-negative decimal with at most 6 decimals.",
      "fraction": 6
    }
  ]
}

• Los códigos son el contrato. type dice qué clase de respuesta es; cada entrada de errors trae su code, y un error que no es de un campo trae el suyo en el propio problema ("code": "entity_not_found"). Son identificadores en inglés que no cambian: úsalos en tu código.
• Los textos están en inglés. title, detail y cada message son para quien lee la respuesta mientras integra y pueden cambiar. Para mostrarle algo a tu cliente, escribe tu propia frase a partir del código, en su idioma: así lo hace nuestra consola, que habla español.
• Los datos de cada código van junto a él. Un too_small trae minimum, origin e inclusive; un invalid_type, expected; un invalid_format, format; un invalid_value, values; un tax_id_mismatch, certificate_tax_id y entity_tax_id. Con ellos escribes la frase sin leer el message.
• En los errores de validación, errors lista cada problema con la ruta del campo tal como la enviaste: lines.0.quantity es la cantidad de la primera línea. Las reglas de forma traen un código genérico (invalid_type, too_small, too_big, invalid_format, invalid_value); las del SRI y las nuestras, uno propio (consumidor_final_limit_exceeded). Pueden aparecer códigos nuevos: trata uno que no conoces por su type.

Un campo desconocido nunca se ignoraCopiar enlace a esta sección

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": "The request is not valid",
  "status": 422,
  "errors": [
    {
      "path": "metdata",
      "code": "unrecognized_keys",
      "message": "Unknown field"
    },
    {
      "path": "lines.0.auxiliary_cod",
      "code": "unrecognized_keys",
      "message": "Unknown field"
    }
  ]
}

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 API key) o establishment al corregir (el número ya está tomado).

TiposCopiar enlace a esta sección

El portal de clientes tiene tres más, para su código de acceso: invalid_code (401, con attempts_left), code_expired (401) y too_many_attempts (429).

Códigos de negocio y ambienteCopiar enlace a esta sección

Una API key ya sabe su negocio y su ambiente, así que ninguna petición los dice. Si envías los encabezados Fiscalbase-Entity o Fiscalbase-Environment y no coinciden con los de tu API key, respondemos 422 con el código entity_mismatch o environment_mismatch. Una persona en la plataforma sí los envía: sin Fiscalbase-Entity, una petición sobre un negocio recibe entity_required en el campo fiscalbase-entity. Un Idempotency-Key repetido por otro negocio recibe 409 con idempotency_key_reused, nunca el comprobante del primero.

Las reglas del SRI son errores de validaciónCopiar enlace a esta secció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.