Gestión de Errores

La API utiliza códigos de estado HTTP estándar para indicar el éxito o fracaso de una solicitud. Aquí encontrarás cómo interpretar las respuestas y manejar errores correctamente.

Códigos de Estado

Éxito (2xx)

200
OK

La solicitud se ha completado correctamente.

201
Created

Recurso creado exitosamente (ej. factura firmada).

Error del Cliente (4xx)

400
Bad Request

Error en los datos de la petición (formato inválido, campos faltantes).

401
Unauthorized

API Key inválida o faltante. Verifica la cabecera X-API-Key.

403
Forbidden

No tienes permisos para esta acción (ej. NIF no coincide con API Key).

404
Not Found

El recurso solicitado no existe.

409
Conflict

Conflicto con el estado actual (ej. factura duplicada, serie bloqueada).

422
Unprocessable Entity

Los datos son válidos pero no se pueden procesar (ej. validación de negocio).

429
Too Many Requests

Has excedido el límite de peticiones. Espera antes de reintentar.

Error del Servidor (5xx)

500
Internal Server Error

Error inesperado en el servidor. Si persiste, contacta soporte.

502
Bad Gateway

Error de comunicación con servicios externos (AEAT, VIES).

503
Service Unavailable

Servicio temporalmente no disponible. Reintenta más tarde.

Formato de Error

Cuando ocurre un error, la respuesta incluye un objeto JSON con información detallada sobre el problema:

Estructura de error
{
  "detail": "Descripción legible del error",
  "code": "ERROR_CODE",
  "field": "campo_con_error",
  "timestamp": "2024-01-30T10:00:00Z"
}

Ejemplos de Errores Comunes

401 API Key inválida
{
  "detail": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}
400 Campo requerido faltante
{
  "detail": "El campo 'issue_date' es obligatorio",
  "code": "MISSING_FIELD",
  "field": "issue_date"
}
403 NIF no autorizado
{
  "detail": "Issuer NIF does not match authenticated API key",
  "code": "NIF_MISMATCH",
  "field": "issuer_nif"
}
409 Factura duplicada
{
  "detail": "Invoice F2024-001 already exists for this issuer",
  "code": "DUPLICATE_INVOICE",
  "existing_id": "550e8400-e29b-41d4-a716-446655440000"
}
429 Rate limit excedido
{
  "detail": "Rate limit exceeded. Try again in 60 seconds",
  "code": "RATE_LIMITED",
  "retry_after": 60
}

Rate Limiting

Para garantizar la estabilidad del servicio, aplicamos límites de peticiones por API Key:

100 peticiones/minuto Límite por defecto para todas las API Keys

Las cabeceras de respuesta incluyen información sobre tu uso actual:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706612460

Mejores Prácticas

1

Implementa reintentos con backoff exponencial

Para errores 5xx y 429, reintenta con delays crecientes: 1s, 2s, 4s, 8s...

2

No reintenties errores 4xx (excepto 429)

Los errores 400, 401, 403, etc. requieren corrección en tu código o datos.

3

Registra los errores con contexto

Guarda el code, detail y timestamp para debugging.

4

Valida datos antes de enviar

Usa los endpoints de validación para NIFs antes de crear facturas.