DEVSDESIGN — DEVELOPERS & DESIGN

API v1 · contrato 1.0.0

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": "…" }
  ]
}
CampoDescripción
titleExplicación legible del problema.
statusCódigo HTTP de la respuesta.
codeIdentificador estable del error. Úsalo en tu lógica.
request_idIdentificador de la solicitud. Inclúyelo al contactar a soporte.
errorsPresente en errores de validación: una entrada por campo, con pointer y detail.

Códigos de error

HTTPCódigoQué ocurrió y cómo resolverlo
401unauthenticatedFalta la API key o no es válida. Revisa el encabezado Authorization.
403forbiddenLa clave no tiene el permiso requerido. Ajusta sus permisos en el portal.
404not_foundEl recurso no existe en esta cuenta o ambiente. Verifica el identificador y que la clave sea del ambiente correcto.
409idempotency_conflictLa Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para una operación distinta.
409sequence_unavailableNo hay secuencia e-NCF disponible para ese tipo. Registra un nuevo rango en el portal.
409encf_already_usedEl e-NCF indicado no es el siguiente disponible. Omite el campo encf para que la API lo asigne.
422validation_failedEl documento no cumple el formato. Revisa la lista errors.
422tax_rule_violationEl total informado no coincide con el cálculo fiscal. Revisa cantidades, precios y tasas.
422invalid_formatEl parámetro format del PDF no es a4 ni pos.
429rate_limitedSuperaste el límite de solicitudes. Espera lo que indique Retry-After.
500artifact_integrity_errorNo se pudo verificar la integridad de un XML o PDF. Reintenta y, si persiste, contacta a soporte.
503service_unavailableUn 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 encabezado X-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.