Errores comunes de la API y cómo resolverlos

Todas las respuestas de error tienen estructura uniforme para facilitar el manejo programático:

{
  "error_code": "snake_case_identificador",
  "message": "Mensaje legible en español o inglés según Accept-Language",
  "request_id": "req_2HxK9...",
  "doc_url": "https://leadsbase.es/help/api/errores-comunes#snake-case-identificador"
}

Siempre incluye request_id cuando contactes con soporte. Nos permite localizar el log exacto en menos de 30 segundos.

400 Bad Request

invalid_parameter

Un parámetro tiene formato incorrecto. Ejemplo:

{
  "error_code": "invalid_parameter",
  "message": "El parámetro 'cif' no es un CIF español válido.",
  "field": "cif",
  "received": "ABC123"
}

Solución: valida formato antes de enviar. CIF español = letra inicial + 7 dígitos + dígito o letra control.

missing_required_field

Falta un campo obligatorio en el body o query string. Comprueba la documentación del endpoint.

body_too_large

El body excede el límite (1 MB por request, 100 MB en endpoints de import). Divide en chunks.

401 Unauthorized

invalid_token

El header Authorization no contiene un token válido. Causas:

• Token expirado (OAuth tras 1h).
• Token revocado manualmente.
• Errata al copiar (espacios, caracteres no imprimibles).

Solución: regenera la API key o renueva el OAuth access_token.

missing_authorization

No has incluido el header Authorization. Recuerda el prefijo Bearer .

403 Forbidden

missing_scope

Tu token no tiene el scope necesario. Ejemplo: usas una key con empresas:read y llamas a un endpoint que requiere empresas:enrich.

Solución: en Ajustes → API keys edita los scopes de la key o genera una nueva con los permisos correctos.

workspace_suspended

Tu workspace está suspendido por impago, fraude o violación de Términos. Revisa el dashboard para más detalle. Contacta con hello@leadsbase.es si crees que es un error.

ip_not_allowed

Configuraste una IP allowlist en la API key y la request viene de una IP distinta. Actualiza la allowlist o desactívala.

404 Not Found

resource_not_found

El CIF, lista o mapa no existe. Comprueba el identificador. Si fue suprimido por RGPD, recibirás 410 Gone en su lugar.

409 Conflict

duplicate_resource

Intentas crear un recurso que ya existe (ej. webhook con la misma URL). El response incluye el ID del recurso existente.

idempotency_key_in_use

Reusaste un Idempotency-Key con un body distinto al original. Las claves deben ser únicas por payload.

410 Gone

data_suppressed_by_rgpd

El registro existió pero fue suprimido tras una solicitud de derecho al olvido. Debes eliminar este registro también de tu sistema. Cabecera X-Suppression-Date indica fecha de la supresión para tu auditoría.

422 Unprocessable Entity

validation_failed

El body es JSON válido pero falla validaciones de negocio. La respuesta lista cada error:

{
  "error_code": "validation_failed",
  "message": "El body no pasa la validación.",
  "errors": [
    { "field": "items[2].cif", "code": "invalid_format" },
    { "field": "items[5].email", "code": "duplicate_in_request" }
  ]
}

429 Too Many Requests

rate_limit_exceeded

Excediste req/min. Respeta Retry-After. Ver rate limits.

concurrent_connections_exceeded

Demasiadas conexiones simultáneas. Reduce paralelismo en tu cliente.

402 Payment Required

insufficient_credits

No te quedan créditos para enriquecimiento. Compra pack adicional o espera al renew.

quota_exceeded

Llegaste al tope de requests del mes. Misma solución.

500 Internal Server Error

Algo falló en nuestro lado. Las respuestas 5xx son seguras de reintentar con backoff. Si persiste más de 5 minutos, revisa status.leadsbase.es.

503 Service Unavailable

Endpoint en mantenimiento o degradado. La cabecera Retry-After te indica cuándo reintentar. Para mantenimientos planificados avisamos con 72h por email a admins.

504 Gateway Timeout

Tu request tardó más del timeout (60s en endpoints normales, 5min en imports). Suele indicar query pesada. Pagina o filtra más.

Debug rápido

Pasos para diagnosticar cualquier error:

1. Apunta el request_id y el error_code.
2. Revisa https://leadsbase.es/admin/api-logs?request_id=<id> para ver el log completo.
3. Si el problema es estructural, contacta con soporte adjuntando el request_id.

Si recibes un error sin documentar aquí, escríbenos a api@leadsbase.es con el request_id. Cada caso nuevo lo añadimos a este catálogo en menos de 48h.

Para autenticación, ver auth. Para límites, ver rate limits.