Errores y estados HTTP

Dos formatos de error

La API tiene dos formatos de error. Es herencia de las dos partes del producto, y el contrato está congelado: los dos siguen como están.

Rutas	Formato	Content-Type
/v1/nfse, /v1/lotes, /v1/webhooks, /v1/eventos	problem+json, con codigo estable	application/problem+json
/v1/account, /v1/usage, /v1/companies, /v1/documents, /v1/servicos, /v1/municipios	Formato de NestJS	application/json

problem+json (emisión, lote, webhooks y eventos):

{
  "type": "https://sudrel.com.br/docs/erros/referencia_duplicada",
  "codigo": "referencia_duplicada",
  "codigo_oficial": null,
  "campo": "/referencia",
  "mensagem": "Já existe uma nota com esta referência nesta empresa.",
  "correcao": "Consulte a nota existente em GET /v1/nfse/9d2f0c1e-3a4b-4c5d-8e9f-0a1b2c3d4e5f. Se quiser emitir outra nota, use outra referência.",
  "retentavel": false,
  "nfse_id": "9d2f0c1e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
  "requisicao_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
}

Campo	Para qué sirve
codigo	Estable. Tu código decide con base en él.
codigo_oficial	Código del Sistema Nacional (ej.: E0240), cuando el error viene de una regla suya.
campo	JSON Pointer del campo con problema en tu cuerpo (ej.: /tomador/documento).
mensagem	Texto para personas. Su redacción puede cambiar; no lo compares.
correcao	Qué hacer.
retentavel	true: repetir la MISMA solicitud puede funcionar. false: corrige antes.
requisicao_id	El mismo valor del encabezado X-Request-Id. Búscalo en Integrações › Log da API (Integraciones › Registro de la API).
erros	En 422 validacao: todos los errores a la vez, cada uno con los campos de arriba.
itens	En 412 empresa_nao_pronta: la preparación completa.
nfse_id, nfse	En 409 referencia_duplicada (solo nfse_id) y en los 422 nfse_rejeitada y falha_transmissao (la nota completa en nfse).

No hay title, status, detail ni instance: el estado está en la respuesta HTTP, y el codigo dice el resto.

Formato de NestJS (cuenta, consumo, empresas, documentos, NBS, municipio):

{ "statusCode": 404, "message": "Empresa não encontrada nesta conta.", "error": "Not Found" }

message puede ser un string o una lista de strings (error de validación de parámetros, un elemento por campo). Aquí no hay requisicao_id en el cuerpo: usa el encabezado X-Request-Id.

Estados HTTP

Estado	Significa	Qué hacer
200	OK	Leer el cuerpo.
201	Creado. En POST /v1/nfse: nota autorizada.	Seguir.
202	Aceptado, todavía en curso (nota transmitindo, lote en validación). No es error.	Darle seguimiento por webhook o GET. No repetir la creación.
204	Eliminado.	Nada.
400	Parámetro de consulta inválido (parametro_invalido), o parámetro desconocido en las rutas de documentos.	Corregir la llamada.
401	Clave ausente, inválida o revocada (nao_autenticado).	Revisar el encabezado Authorization y la clave.
403	La clave no puede hacer esto: restringida a otra empresa (acesso_negado, chave_restrita) o clave de prueba en una operación solo de producción.	Usar la clave correcta.
404	No existe en esta cuenta ni en este entorno.	Revisar el id y el entorno de la clave.
409	Conflicto: referencia_duplicada, idempotencia_conflito, conflito, referencia_ambigua, estado que no permite la operación.	Leer codigo. Ver Idempotencia.
410	cursor_vencido en /v1/eventos.	Continuar desde cursor_mais_antigo.
412	empresa_nao_pronta: la empresa no puede emitir. No se creó nada.	Resolver los elementos en bloqueio de itens. Ver Preparación.
413	Hoja de cálculo de más de 20 MB en POST /v1/lotes.	Dividir la hoja de cálculo.
422	La solicitud se entendió y se rechazó: validacao, nfse_rejeitada, falha_transmissao, cancelamento_recusado...	Leer codigo, erros, correcao.
429	Más de 120 solicitudes por minuto, en esta clave.	Esperar al cambio de minuto y repetir.
500	Error nuestro (erro_interno, retentavel: true).	Repetir con la misma Idempotency-Key. Si persiste, envía el X-Request-Id a soporte.

El 429 también tiene los dos formatos: problem+json limite_de_requisicoes (retentavel: true) en las rutas de emisión, lote, webhooks y eventos, y {"message": "...", "code": "RATE_LIMITED"} en las demás. No hay encabezado Retry-After ni X-RateLimit-*.

Códigos (codigo) de las rutas problem+json

codigo	Estado	Cuándo
parametro_invalido	400	Filtro, fecha, limite o cursor inválido
requisicao_invalida	400	Solicitud mal formada
nao_autenticado	401	Clave ausente, inválida o revocada
acesso_negado	403	Clave restringida a otra empresa
chave_restrita	403	Clave restringida a una empresa que intenta administrar webhooks
nao_encontrado	404	Empresa inexistente, o nota todavía sin XML
nfse_nao_encontrada	404	Ninguna nota con ese id, referencia o clave de acceso
lote_nao_encontrado	404	Lote inexistente
empresa_nao_encontrada	404	empresa_id inexistente en POST /v1/lotes
referencia_duplicada	409	Ya existe una nota con esa referencia en esta empresa y entorno
idempotencia_conflito	409	Misma Idempotency-Key con otro cuerpo
conflito	409	La misma Idempotency-Key todavía está en curso
referencia_ambigua	409	La referencia existe en más de una empresa: indica empresa_id
nfse_sem_pdf	409	La nota todavía no tiene PDF (retentavel: true)
nfse_nao_aguarda_confirmacao	409	Confirmación de una nota que no está en aguardando_confirmacao
lote_sem_emissao_manual, lote_validando, lote_ja_emitido	409	POST /v1/lotes/{id}/emissao fuera de momento
cursor_vencido	410	Cursor de eventos con más de 90 días
empresa_nao_pronta	412	Preparación con bloqueio
validacao	422	Cuerpo inválido; los detalles están en erros
nfse_rejeitada	422	El Sistema Nacional rechazó la nota
falha_transmissao	422	No se pudo concluir la transmisión
cancelamento_recusado	422	El Sistema Nacional rechazó la cancelación
planilha_obrigatoria	422	POST /v1/lotes multipart sin el archivo
simulacao_so_no_sandbox, simulacao_invalida	422	Simulador con la clave de producción, o escenario inexistente
reenvio_invalido, evento_nao_assinado	422	Reenvío de webhook con parámetros incorrectos
limite_de_requisicoes	429	Límite de solicitudes
erro_interno	500	Error nuestro

Dentro de erros (422 validacao) los códigos indican qué campo y qué regla: tipo_invalido, formato_invalido, campo_desconhecido, documento_invalido, referencia_muito_longa, tomador_igual_prestador, codigo_servico_inexistente, aliquota_iss_obrigatoria, competencia_invalida, obra_obrigatoria, nbs_fora_do_servico y otros. Cada uno viene con campo, mensagem y correcao; trata cualquier código nuevo por el campo y la correcao.

Rechazo del Sistema Nacional

Cuando el Sistema Nacional rechaza, el 422 nfse_rejeitada trae codigo_oficial (ej.: E0039) y la nota completa en nfse. En nfse.rejeicao.explicacao, para los códigos que Sudrel conoce, viene la explicación en portugués claro y la corrección. La nota queda registrada como rejeitada: corrige y emite una nota nueva, con otra referencia.