Errores
Todos los códigos de error de la API y del servidor MCP de findbytown, con su estado HTTP y qué hacer.
Un error tiene el estado HTTP indicado abajo y este cuerpo. error es estable: básate en él, no en message, cuya redacción puede cambiar. Indica requestId cuando nos escribas; también está en la cabecera X-Request-Id.
{
"error": "quota_exhausted",
"message": "Monthly reveal quota exhausted.",
"details": {
"resetAt": "2030-01-01T00:00:00.000Z"
},
"requestId": "00000000-0000-4000-8000-000000000000"
}Un 429 lleva además Retry-After, en segundos. Un 401 lleva WWW-Authenticate: Bearer.
| Código | Estado HTTP | Significado |
|---|---|---|
| validation_error | 400 | Falta un parámetro o su formato es incorrecto. details indica cuál. |
| unknown_parameter | 400 | Este endpoint no reconoce un parámetro de consulta, normalmente por un error de escritura. details indica cuál. |
| use_reveal_endpoint | 400 | Has enviado reveal= en una lectura. Las lecturas nunca gastan cuota: usa el endpoint de revelación. |
| bad_id | 400 | El id de la empresa no es un entero positivo. |
| missing_api_key | 401 | No hay cabecera Authorization, o está vacía. |
| invalid_api_key | 401 | La clave no existe o ha sido revocada. |
| quota_exhausted | 402 | No quedan revelaciones en este periodo. details contiene la fecha de reinicio. La lectura sigue disponible. |
| plan_without_api | 403 | El plan actual de la cuenta no incluye la API. Se aplica desde el momento en que termina un plan. |
| suspended | 403 | La cuenta está suspendida. Sus claves vuelven a funcionar si se levanta la suspensión. |
| bad_origin | 403 | Solo MCP: la cabecera Origin del navegador no es uno de nuestros hosts. |
| not_found | 404 | Esa empresa no existe, o se retiró a petición de su propietario. |
| method_not_allowed | 405 | Solo MCP: GET y DELETE no están disponibles, usa POST. |
| email_invalid | 409 | El email de esta empresa está marcado como no válido, así que no se puede revelar. No se ha gastado nada. |
| payload_too_large | 413 | Solo MCP: el cuerpo de la solicitud es demasiado grande. |
| rate_limited | 429 | Demasiadas solicitudes este minuto. Espera los segundos que indica Retry-After. |
| budget_exhausted | 429 | Has alcanzado el presupuesto de hoy de empresas distintas. Las empresas ya vistas hoy siguen pasando. Retry-After indica cuándo se reinicia. |
| blocked | 429 | El acceso a los datos de empresas está temporalmente en pausa por uso automatizado, como recorrer ids. Retry-After indica el tiempo restante. Escribe a soporte si es un error. |
| internal_error | 500 | Algo ha fallado por nuestra parte. Indica requestId al escribir a soporte. |
| reveals_unavailable | 503 | Las revelaciones no están disponibles por un momento y no se ha gastado nada. Inténtalo de nuevo en breve. |