Errores

Los errores responden con Content-Type: application/problem+json, el formato de la RFC 9457:

{
  "type": "https://nomenclator.com.ar/problems/insufficient-scope",
  "title": "Esta key es de solo lectura",
  "status": 403,
  "detail": "Esta key solo puede leer. Creá una con alcance classify para clasificar.",
  "instance": "/v1/classifications",
  "request_id": "req_3RYG87TTVTDR"
}

string

requerido

URI estable del tipo de error. Tu integración decide por este campo, nunca por title ni por detail, que pueden cambiar de redacción.

string

requerido

Resumen fijo por tipo, en castellano.

integer

requerido

El código HTTP, repetido en el cuerpo.

string

requerido

Qué pasó en este pedido puntual. Es seguro mostrarlo a una persona.

string

requerido

La ruta del pedido que falló.

string

requerido

El mismo valor que el header X-Request-Id. Citalo si nos escribís.

array

Solo en validation-error y en los errores de formato: un elemento por campo inválido, con field (ruta con puntos, como items[2].ncm), code y message.

Catálogo

El type es https://nomenclator.com.ar/problems/ seguido del nombre de la tabla.

`type`	Status	Qué significa	Qué hacer
`validation-error`	422	El cuerpo o un parámetro no es válido.	Corregí lo que dice `errors`.
`idempotency-key-invalid`	422	Falta `Idempotency-Key` o no tiene el formato.	Mirá idempotencia.
`idempotency-key-reused`	422	Usaste la clave con otro cuerpo.	Usá otra clave.
`idempotency-key-in-flight`	409	El pedido anterior con esa clave sigue en curso.	Esperá y reintentá con la misma clave.
`unauthenticated`	401	Falta la key, no existe o fue revocada.	Revisá el header `Authorization`.
`insufficient-scope`	403	La key es `read` y el pedido necesita `classify`.	Usá una key `classify`.
`plan-without-api`	403	El plan no incluye la API.	Escribinos para habilitarla.
`api-suspended`	403	El acceso por API está suspendido.	Escribinos.
`subscription-inactive`	403	La suscripción no está activa.	Un admin la regulariza desde la app.
`organization-archived`	403	La organización está archivada.	Un owner la restaura desde la app.
`terms-acceptance-required`	403	Hay Términos nuevos sin aceptar.	Un admin los acepta desde la app.
`forbidden`	403	La operación no está permitida.	Revisá el pedido.
`not-found`	404	No existe, o no es de tu organización.	Revisá el id.
`conflict`	409	El estado actual no permite la acción.	Por ejemplo, responder una clasificación que no espera respuestas, o pedir el PDF antes de que se resuelva.
`payload-too-large`	413	El archivo pasa los 10 MB.	Subí un PDF más chico.
`unsupported-media-type`	415	El cuerpo no es JSON.	Mandá `Content-Type: application/json`.
`rate-limited`	429	Superaste un límite.	Esperá lo que diga `Retry-After`. Mirá límites.
`internal-error`	500	Algo se rompió de nuestro lado.	Reintentá; si sigue, escribinos con el `request_id`.
`upstream-unavailable`	502	Un servicio interno no respondió.	Reintentá en unos segundos.
`classifier-unavailable`	503	El clasificador no está disponible.	Reintentá más tarde.
`maintenance`	503	Nomenclator está en mantenimiento.	Esperá lo que diga `Retry-After`.

Pueden aparecer tipos nuevos. Tratá un type desconocido según su status.

Reintentos

4xx: no reintentes sin cambiar algo, salvo 409 idempotency-key-in-flight y 429.
5xx: reintentá con espera creciente. En POST /classifications y en las respuestas, reintentá con la misma Idempotency-Key.

Empezá acá

Conceptos

Clasificaciones

Referencia arancelaria

Cuenta

Catálogo

Reintentos

​Catálogo

​Reintentos

Catálogo

Reintentos