Skip to main content
Formato de error La API de SPI devuelve los errores como problem details de RFC 9457 con el tipo de medio application/problem+json:
Definiciones de campos
  • type – Un URI que identifica el error en el catálogo de errores de Lerian, construido como https://errors.lerian.studio/v1/<code>. Una respuesta sin code lleva el valor predeterminado de RFC about:blank.
  • title – El texto del estado HTTP (por ejemplo, Unprocessable Entity).
  • status – El código de estado HTTP.
  • detail – Una explicación legible de esta ocurrencia. El texto varía según la ocurrencia, así que decide la rama con code.
  • code – Un identificador estable para la condición. Una solicitud que el riel rechazó antes de que llegara a un handler no lleva code. Esta API usa dos vocabularios aquí: los propios códigos SPI-NNNN del riel, y los tokens del directorio de claves Pix que se describen más adelante.
  • errors – Lista opcional de detalles de validación por campo, cada uno con un message, una location y el value que causó el problema.
  • correlationId – El identificador de correlación con alcance de la solicitud. Cita este valor en una solicitud de soporte.
En las respuestas 5xx, el riel reemplaza detail por internal error, así que las causas internas no quedan expuestas. Usa code para decidir la rama de forma programática.

​
Códigos del riel

Los códigos SPI-NNNN nombran las condiciones que el propio riel de SPI evalúa. El dígito después del prefijo los agrupa: 0 entrada, 1 transporte del riel, 2 autorización, 3 procesamiento, 4 límite de solicitudes y cuota, 9 reserva. Cuatro códigos llevan más de un estado, porque la condición que nombran tiene más de una forma en este riel. Cada uno aparece abajo bajo cada estado con el que puede llegar. Cuando BACEN rechaza un pago, el rechazo lleva el motivo de estado ISO 20022 propio de la red. RJCT es el que nombra un rechazo. En la superficie de la API, SPI-1002 es el código para ese rechazo. Para encontrar qué pagos rechazó la red, consulta el informe de pagos rechazados. Enumera cada uno por estado terminal e id end-to-end.

​
401: No autenticado

​
403: Prohibido

​
404: No encontrado

​
409: Conflicto

​
413: Payload demasiado grande

​
422: No procesable

​
429: Demasiadas solicitudes

​
500: Error del servidor

​
502: Gateway incorrecto

​
503: Servicio no disponible

Estos códigos nombran condiciones de dependencias. Aplica backoff y reintenta.

​
504: Timeout del gateway

​
Tokens del directorio de claves Pix

El directorio de claves Pix mantiene su propio vocabulario de errores, y el riel lo reenvía. Un rechazo del directorio te llega con el token propio del directorio en code y el estado HTTP propio del directorio en status. El URI de type lleva el mismo token como su último segmento. Este vocabulario pertenece al directorio, así que trátalo como abierto. Maneja un token que no reconozcas por su status, y lee el token mismo como el motivo. Las tablas siguientes cubren los tokens que el riel maneja hoy, en el registro de claves, la búsqueda de claves, la eliminación de claves y las operaciones de reclamo.
Un rechazo por rate limit del directorio te llega como SPI-4001 con HTTP 429. Cuando el directorio prescribió una espera, la respuesta la lleva en Retry-After. Consulta los códigos del riel más arriba.

​
General

​
Registro de claves

​
Reclamos de claves

​
Rechazos de archivo de BR Code

El canal de archivos por lotes de BR Code responde a una remessa enviada línea por línea. Una línea aceptada liquida. Una línea rechazada lleva un código de rechazo de tres dígitos. También lleva el nombre de campo y la descripción que el esquema Pix publica para ese código. Tu conciliación mapea la respuesta contra la hoja de errores propia del esquema. Dos rechazos rechazan una línea antes de que se ejecute cualquier regla de negocio, así que son los primeros que encuentra una integración nueva. 063 (Cadastro, Cliente nao cadastrado) dice que el encabezado del archivo nombra a un recebedor para el cual este despliegue no tiene un perfil registrado. 096 (Registro, Inválido) dice que el esquema rechazó el registro y no publica un código más específico para el campo en falta. Un registro de longitud incorrecta es uno de estos casos. Otros cuatro cubren los dos identificadores que lleva la mayoría de las líneas. 012 (Chave pix, Chave inválida) dice que la línea cobra sobre una clave Pix para la cual este despliegue no tiene un recebedor registrado. 014 (Chave pix, Não é compatível com o cnpj ou agência e conta informada) nombra una clave registrada a otro recebedor. El encabezado del archivo resuelve a uno distinto. 016 (Identificador (txid), Em duplicidade) dice que el txid se repite. 017 (Identificador (txid), Inválido ou não encontrado) dice que el movimiento nombra un cobro que este riel no tiene. La hoja de errores del esquema publica muchos más códigos. El canal renderiza el subconjunto sobre el que mapean sus propios rechazos. Cada línea rechazada nombra su campo, así que lee primero el nombre del campo y después el código.