Errores
Formato de error, códigos y cómo resolver cada caso.
Formato de error
Los errores usan el formato application/problem+json. El código HTTP indica la clase de problema y el campo code lo identifica de forma estable, para que tu programa pueda reaccionar.
Ejemplo de error de validación
{
"type": "https://docs.devsdesign.do/errors/validation_failed",
"title": "Faltan referencias fiscales requeridas para este tipo de e-CF.",
"status": 422,
"code": "validation_failed",
"request_id": "req_…",
"errors": [
{ "code": "required", "pointer": "/references", "detail": "…" }
]
}
| Campo | Descripción |
|---|---|
title | Explicación legible del problema. |
status | Código HTTP de la respuesta. |
code | Identificador estable del error. Úsalo en tu lógica. |
request_id | Identificador de la solicitud. Inclúyelo al contactar a soporte. |
errors | Presente en errores de validación: una entrada por campo, con pointer y detail. |
Códigos de error
| HTTP | Código | Qué ocurrió y cómo resolverlo |
|---|---|---|
| 401 | unauthenticated | Falta la API key o no es válida. Revisa el encabezado Authorization. |
| 403 | forbidden | La clave no tiene el permiso requerido. Ajusta sus permisos en el portal. |
| 404 | not_found | El recurso no existe en esta cuenta o ambiente. Verifica el identificador y que la clave sea del ambiente correcto. |
| 409 | idempotency_conflict | La Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para una operación distinta. |
| 409 | sequence_unavailable | No hay secuencia e-NCF disponible para ese tipo. Registra un nuevo rango en el portal. |
| 409 | encf_already_used | El e-NCF indicado no es el siguiente disponible. Omite el campo encf para que la API lo asigne. |
| 422 | validation_failed | El documento no cumple el formato. Revisa la lista errors. |
| 422 | tax_rule_violation | El total informado no coincide con el cálculo fiscal. Revisa cantidades, precios y tasas. |
| 422 | invalid_format | El parámetro format del PDF no es a4 ni pos. |
| 429 | rate_limited | Superaste el límite de solicitudes. Espera lo que indique Retry-After. |
| 500 | artifact_integrity_error | No se pudo verificar la integridad de un XML o PDF. Reintenta y, si persiste, contacta a soporte. |
| 503 | service_unavailable | Un componente no está disponible temporalmente. Reintenta con esperas crecientes. |
Cómo pedir ayuda con un error
Al abrir un ticket, incluye:
- El valor de
request_id(o del encabezadoX-Request-Id). - El identificador del comprobante (
doc_…), si existe. - La fecha y hora aproximadas, y el ambiente (pruebas o producción).
No incluyas tu API key ni tu certificado.
¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.