Errores

Los errores se devuelven con Content-Type: application/problem+json y esta forma:

{
    "type": "urn:auditium:api:error:ambito-insuficiente",
    "title": "Comitente fuera de alcance",
    "status": 403,
    "detail": "No se encuentra habilitado para consultar el/los comitente/s: 9999.",
    "instance": "/ruc/api/asignaciones_personal?id_comitente=9999",
    "_links": [
        { "href": "https://developers.auditium.com.ar/errores/ambito-insuficiente", "rel": "help", "method": "GET" }
    ]
}

Campo	Descripción
type	Identificador del tipo de error. Es estable: es el campo por el que hay que discriminar desde el código.
title	Resumen del tipo de error.
status	Código HTTP, repetido en el cuerpo.
detail	Explicación de esta ocurrencia. Es prosa y puede cambiar: no discriminar por este campo.
instance	Ruta de la petición que produjo el error.
_links	El primer elemento es siempre el link rel: help a la página de este catálogo.

El type es un identificador, no una URL: no hay que resolverlo por HTTP. La página navegable de cada tipo viaja en _links, y es la que está enlazada en la tabla de abajo.

Catálogo

type	HTTP	Qué pasó
credenciales-ausentes	400 / 401	No se envió el header Authorization
credenciales-invalidas	401	La credencial enviada no sirve
capacidad-insuficiente	403	El endpoint o el método no está habilitado para tus credenciales
ambito-insuficiente	403	Pediste datos de un comitente fuera de tu alcance
endpoint-inexistente	404	La ruta invocada no existe
parametro-requerido	400	Falta un parámetro obligatorio
parametro-invalido	400	Un parámetro tiene un valor que no admite
transporte-no-admitido	400	La petición no usó HTTPS, o el método no es admitido
formato-no-admitido	415	El cuerpo no se envió como multipart/form-data
lote-demasiado-grande	413	El lote trae más documentos que el máximo del requisito
validacion	422	Los valores enviados violan una regla de negocio

Rechazos por documento

Estos tres describen un documento de un lote de POST /presentaciones, no la petición entera. Viajan en rechazados[] dentro de un 201 cuando al menos un documento se presentó, o en errors[] dentro de un 422 cuando ninguno lo hizo.

type	Quién lo corrige	Qué pasó
documento-rechazado	el cliente	La identificación no resuelve, no es un PDF, o el requisito no aplica a ese recurso
archivo-demasiado-grande	el cliente	El archivo excede el tope de tamaño del requisito
auditoria-inexistente	Auditium	Falta un registro interno. No requiere acción de tu parte

Los type de las tablas van siempre precedidos por urn:auditium:api:error: en el cuerpo de la respuesta. Por ejemplo, el tipo parametro-requerido llega como urn:auditium:api:error:parametro-requerido.

Cómo discriminar errores

TYPE=$(curl -s https://auditium.com.ar/ruc/api/asignaciones_personal \
            -H "Authorization: Bearer $TOKEN" | jq -r '.type // empty')

case "$TYPE" in
    urn:auditium:api:error:credenciales-invalidas) ;; # renovar token y reintentar
    urn:auditium:api:error:ambito-insuficiente)    ;; # revisar id_comitente
    urn:auditium:api:error:parametro-requerido)    ;; # corregir la petición
esac

Un type desconocido debe tratarse como error genérico del código HTTP que acompaña: el catálogo puede crecer.