Falta la autenticación
La petición no trae la cabecera «Authorization: Bearer <token>».
Autenticación
El token falta, no es válido o ya no sirve. Responden 401 con la cabecera WWW-Authenticate.
Token no válido
El token está incompleto, mal copiado o no existe. Revise que lo pegó entero.
Token de otro ambiente
El token es del otro ambiente (ak_live_ o ak_test_); el detalle indica la URL base correcta.
Token revocado
El token fue revocado desde Arithmetik Cloud y ya no autentica. Cree uno nuevo.
Token vencido
El token pasó su fecha de vencimiento. Cree uno nuevo.
Empresa, plan y permisos
El token es válido, pero la empresa no puede usar la API en este momento o el token no tiene el alcance necesario.
Empresa inactiva
La empresa del token no está activa en Arithmetik Cloud.
demo_tenant
403Empresa de demostración
Las empresas de demostración no pueden usar la API.
Suscripción suspendida
La suscripción de la empresa está suspendida; renuévela para seguir usando la API.
Empresa fuera de producción
Los tokens live exigen que la empresa esté en el ambiente de Producción de la DGII.
Sin acceso a la API
La empresa no tiene acceso a la API en este ambiente: en producción la API viene incluida en el plan, así que falta un plan activo o su suscripción API (si tiene una) está suspendida, cancelada o vencida; en el sandbox, falta el paquete de pruebas activo.
Alcance insuficiente
El token no tiene el alcance que exige esta operación (ver requiredScopes).
Límites y cuotas
Respetan la cabecera Retry-After: espere esos segundos antes de reintentar.
rate_limited
429Demasiadas peticiones
Se superó el límite de peticiones; espere los segundos que indica Retry-After.
Cuota de e-CF agotada
Se agotó la cuota de e-CF del período; violatedPolicy indica si fue la mensual o la diaria.
Idempotencia
POST /ecf exige Idempotency-Key; externalId es su referencia única por empresa.
Falta Idempotency-Key
Esta operación exige la cabecera Idempotency-Key (1 a 255 caracteres ASCII visibles).
Idempotency-Key reutilizada
La misma Idempotency-Key ya se usó con otra petición (otro cuerpo, método o ruta).
Petición en curso
Otra petición con la misma Idempotency-Key se está procesando; reintente tras Retry-After.
externalId en uso
La empresa ya tiene un e-CF con ese externalId; el problema trae su id.
Petición
El cuerpo, un parámetro, el método o la ruta no son válidos; errors[] señala cada campo. Una ruta que no existe bajo /api/v1 responde not_found y un método que la ruta no admite, method_not_allowed con la cabecera Allow.
Datos no válidos
El cuerpo no cumple el esquema o las reglas fiscales; errors[] señala cada campo con un puntero JSON.
invalid_json
400JSON no válido
El cuerpo está vacío o no es JSON válido en UTF-8.
Cuerpo demasiado grande
El cuerpo de la petición supera el tamaño máximo admitido.
Petición no válida
Un parámetro de la ruta o de la consulta no es válido.
not_found
404No encontrado
El recurso no existe o no pertenece a la empresa del token.
Método no admitido
La ruta no admite este método HTTP.
Documento y emisión
El e-CF o la empresa no admiten la operación en su estado actual, o hay otra operación en curso sobre el mismo documento (reintente tras Retry-After).
Estado no válido
El documento no admite esta operación en su estado actual.
Envío en curso
El documento se está enviando a la DGII en este momento; reintente en unos segundos.
Nota en curso
Otra nota sobre el mismo comprobante se está emitiendo; reintente tras Retry-After.
not_signed
409Documento sin firmar
El e-CF todavía no está firmado, así que no tiene XML firmado; consulte su estado más tarde.
No se puede reenviar
Sólo se reenvía un e-CF pendiente que nunca llegó a la DGII o uno rechazado cuyo e-NCF la DGII no usó (dgii.sequenceUsed = false).
Certificado no disponible
La empresa no tiene un certificado digital vigente o tiene la firma deshabilitada.
Secuencia no disponible
No hay una secuencia de e-NCF activa, vigente y con números disponibles para el tipo de comprobante.
Función no disponible
La petición usa una función que la API todavía no admite.
Servicio
Problemas del lado de Arithmetik Cloud o de un servicio del que depende.
Sandbox no disponible
El sandbox no puede firmar documentos en este momento; vuelva a intentarlo más tarde.
Servicio no disponible
La API está deshabilitada temporalmente o un servicio del que depende no responde.
Error interno
Error no previsto. Escriba a soporte indicando el requestId.
Miembros del problema
Además de los miembros del RFC 9457, cada error trae code y requestId, y algunos agregan miembros propios. Es el esquema Problem de la especificación OpenAPI; ignore los miembros que no conozca: pueden agregarse otros.
| Miembro | Qué contiene |
|---|---|
type | URL de la documentación del código. |
title | Título fijo del código. |
status | Código HTTP. |
detail | Qué pasó en este caso, en español. Su redacción puede cambiar: no lo compare en su código. |
instance | Ruta de la petición. |
code | Código estable del error. Úselo en su código. |
requestId | Identificador de la petición (también en la cabecera X-Request-Id). Inclúyalo si escribe a soporte. |
errors[] | Errores por campo (validation_failed, invalid_request, unsupported_feature). Miembros: pointer, parameter, message. |
dgii | El documento ante la DGII, cuando el problema depende de eso (p. ej. not_resendable). Miembros: status, code, sequenceUsed, trackId, messages. |
violatedPolicy | quota_exceeded: el tope alcanzado. Valores: monthly, daily. |
limit | quota_exceeded / rate_limited: el límite. |
used | quota_exceeded: lo usado en el período. |
retryAfterSeconds | rate_limited: segundos de espera (también en Retry-After). |
requiredScopes[] | insufficient_scope: los alcances que exige la operación. |
missingScopes[] | insufficient_scope: los que le faltan al token. |
id | external_id_taken: el id del e-CF que ya tiene esa referencia. |
baseUrl | wrong_environment: la URL base correcta para el token. |
tokenEnvironment | wrong_environment: el ambiente del token. Valores: live, sandbox. |
maxBytes | payload_too_large: el tamaño máximo del cuerpo, en bytes. |
noteGuard[] | validation_failed de una nota 33/34: las observaciones de la revisión previa al envío. Miembros: code, severity, message. |