Errores
Todas las APIs de NamiDB Cloud devuelven los errores con la misma forma:
{"error": {"code": "plan_limit", "message": "…", "request_id": "…"}}- Decide según
code. Los códigos son estables; los mensajes son para personas y pueden cambiar. - Incluye el
request_id(también en la cabecerax-request-id) cuando contactes a soporte. Retry-After(en segundos) viene con429y con503 engine_starting.
Los SDKs los lanzan como NamiDBError con los mismos code, status,
request_id y retry_after.
API de datos
Estos vienen de db.namidb.com por HTTP y MCP. Por Bolt, las mismas
condiciones son fallos de Bolt con el código de Neo4j indicado.
| Código | Estado | Bolt | Significado | Qué hacer |
|---|---|---|---|---|
unauthorized | 401 | Security.Unauthorized | La key falta, es inválida, está revocada o venció | Revisa la key; crea una nueva si se revocó o venció |
database_not_in_scope | 403 | Security.Forbidden | La key no tiene alcance sobre esta base de datos | Usa una key que la cubra, o nombra una base de datos dentro de su alcance |
read_only_key | 403 | Security.Forbidden | Se envió una escritura con una key de solo lectura | Usa una key de lectura y escritura para escribir |
ip_not_allowed | 403 | Security.Forbidden, conexión cerrada | La dirección del cliente está fuera de la IP allowlist de la organización o de la key; el mensaje indica la dirección y la lista | Agrega la dirección en API keys → IP allowlist |
org_paused | 403 | Security.Forbidden, conexión cerrada | Una organización Free se pausó después de 7 días sin actividad | Reanúdala desde la consola |
org_suspended | 403 | Security.Forbidden, conexión cerrada | NamiDB suspendió la organización; el mensaje incluye el motivo | Contacta a soporte |
access_banned | 403 | Security.Forbidden, conexión cerrada | NamiDB bloqueó la petición por abuso: la dirección del cliente está bloqueada, o lo están la organización o la key (el mensaje dice cuál) | No se reintenta. Si crees que es un error, escribe a info@namidb.com |
database_not_found | 404 | No hay ninguna base de datos con ese nombre | Revisa el nombre (GET /v1/databases) | |
query_not_found | 404 | La sentencia que querías cancelar ya no se está ejecutando (terminó, o la base de datos está dormida) | Nada que hacer | |
payload_too_large | 413 | Cuerpo de la petición de más de 2 MiB | Envía lotes más pequeños | |
result_too_large | 413 | Resultado de más de 64 MiB | LIMIT, pagina o devuelve menos propiedades | |
plan_limit | 429 | Security.Forbidden | Se agotó una cuota con el spend cap activado, o la base de datos es de solo lectura después de bajar de plan | Sube de plan, desactiva el cap, elimina una base de datos o espera a que se reinicie el periodo |
rate_limited | 429 | TransientError | Demasiadas peticiones por segundo, consultas concurrentes o sesiones Bolt, o demasiadas keys inválidas desde esta dirección | Espera Retry-After y reintenta; suaviza las ráfagas |
engine_starting | 503 | La base de datos está despertando de la inactividad | Reintenta después de Retry-After (1 s); no se ejecutó nada | |
database_unavailable | 503 | La base de datos se está restaurando, o su restauración falló | Espera a que esté ready, o elimina una que falló | |
engine_unavailable | 502 | No se pudo llegar al motor | Reintenta las lecturas; para las escrituras, verifica antes de reintentar | |
control_plane_unavailable | 502 | No se pudo verificar la key en este momento | Reintenta con backoff; no se ejecutó nada | |
bad_request | 400 | Petición mal formada (no es JSON, falta query, …) | Corrige la petición | |
internal | 500 | Error inesperado | Reintenta más tarde; contacta a soporte con el id de petición |
Errores del motor
Los errores del propio motor se transmiten con su estado, por HTTP, MCP y Bolt (con los códigos de Neo4j del motor y, en Bolt 5.7, GQLSTATUS):
| Código | Estado | Significado |
|---|---|---|
parse_error | 400 | El Cypher no se puede parsear |
plan_error, unsupported | 400 | Cypher válido que NamiDB no puede planificar, o una funcionalidad que no soporta |
eval_error | 400 | Un error en tiempo de ejecución (tipos incompatibles, división por cero, …) |
constraint | 409 | Se violó un constraint de unicidad u otro |
cancelled | 409 | La sentencia se canceló (pestaña Activity o la API de cancelación) |
row_cap | 413 | El resultado tiene más filas de las que puede devolver una consulta |
query_memory_limit | 413 | La consulta necesita más memoria de trabajo de la que el tamaño de base de datos de tu plan permite para una sola consulta. Por Bolt: Neo.ClientError.Statement.ResourceLimitExceeded |
memory_pressure | 503 | A la base de datos le falta memoria para consultas en este momento, normalmente porque hay varias consultas grandes ejecutándose a la vez. Por Bolt: Neo.TransientError.General.DatabaseUnavailable |
timeout | 504 | Superó el timeout de consulta del plan (10 s / 30 s / 60 s) |
Consulta el Cypher soportado para saber qué acepta el motor. Los timeouts y los topes de filas no se pueden reintentar tal cual: acota la consulta.
query_memory_limit (413) tampoco se puede reintentar: la misma consulta
necesita la misma memoria en cada ejecución, y una escritura que lo recibe no
confirma nada. Haz que cada paso retenga menos: filtra y agrega LIMIT lo
antes posible, pagina con ORDER BY … SKIP … LIMIT o con un rango de claves,
devuelve menos valores o valores más pequeños, y agrega (count(*), sum())
en lugar de devolver filas crudas o juntarlas con collect(). El límite crece
con el tamaño de base de datos del plan.
memory_pressure (503) es transitorio: otras consultas están usando la
memoria de consultas de la base de datos en este momento. Reintenta con
backoff exponencial. Los drivers de Neo4j lo reintentan por su cuenta, porque
llega como TransientError. Si se repite, distribuye en el tiempo tus
consultas grandes o hazlas más pequeñas, y consume o cierra los resultados de
Bolt sin demora: un resultado que todavía no se leyó conserva su memoria.
MCP
Por MCP, los errores de autenticación y de base de datos son errores HTTP como
los de arriba. Los errores al ejecutar una herramienta (límites, errores de
Cypher) son resultados de la herramienta con isError: true y este JSON de
error como texto.
API de gestión
Desde app.namidb.com/api/v1:
| Código | Estado | Significado |
|---|---|---|
bad_request | 400 | Entrada inválida; details.field indica la propiedad (por ejemplo at para una restauración a un punto en el tiempo en el futuro) |
reserved_name | 400 | backups, exports y tenants, y los nombres que empiezan con nmdbexp-, no pueden ser nombres de bases de datos |
unauthorized | 401 | Token ausente o inválido (una API key enviada aquí también recibe esto) |
token_expired, token_revoked | 401 | El token venció o fue revocado |
insufficient_scope | 403 | El scope del token no permite la operación |
token_inactive | 403 | Quien lo creó perdió el acceso de owner/admin, fue bloqueado o ya no cumple la exigencia de dos pasos o de SSO de la organización; o el token que lo creó a través de la API ya no funciona |
org_suspended | 403 | La organización está suspendida |
org_export_only | 403 | La organización está suspendida o eliminada: solo funcionan las exportaciones |
ip_not_allowed | 403 | Una solicitud o descarga de exportación desde fuera de la IP allowlist de la organización |
forbidden | 403 | No permitido por otro motivo (por ejemplo, quitar a un owner) |
plan_limit | 403 | Se superó un límite: bases de datos, API keys, tokens de gestión activos (25), entradas de IP allowlists |
aal2_required | 403 | La acción necesita un segundo factor |
not_found, database_not_found | 404 | No existe ese recurso |
conflict | 409 | El estado actual no lo permite (por ejemplo, responder a un ticket cerrado) |
name_taken | 409 | Ya existe una base de datos con ese nombre |
name_purging | 409 | Una base de datos eliminada con ese nombre todavía se está borrando |
database_unavailable | 409 | La base de datos no está lista |
backup_in_progress | 409 | Ya hay un backup de esta base de datos en ejecución |
backup_not_ready | 409 | El backup no terminó con éxito, así que no se puede restaurar |
export_in_progress | 409 | Ya hay una exportación de esta base de datos en ejecución |
no_backup, no_backup_before | 409 | No hay nada desde lo cual clonar o restaurar (en ese momento) |
key_inactive, already_rotated | 409 | La key está revocada o vencida, o ya se rotó |
already_member, already_invited, invite_closed | 409 | Conflictos en el estado de la invitación |
last_owner | 409 | La organización tiene que conservar un owner |
idempotency_in_progress | 409 | Una petición con este Idempotency-Key todavía se está ejecutando |
export_expired | 410 | Los archivos de la exportación se eliminaron después de 7 días |
payload_too_large | 413 | Cuerpo de más de 64 KiB |
unsupported_media_type | 415 | Envía Content-Type: application/json |
lifetime_policy | 422 | El vencimiento supera la política de vida útil de keys de la organización |
idempotency_key_reused | 422 | La key se usó para una petición distinta |
rate_limited | 429 | Más de 300 peticiones por minuto, o se agotó un presupuesto por hora; espera Retry-After |
internal | 500 | Error inesperado |
not_implemented | 501 | Reservado para una operación documentada antes de estar disponible |
control_plane_unavailable | 503 | Reintenta con backoff |
Códigos del lado del cliente en los SDKs
Los lanzan los SDKs antes de recibir una respuesta o sin ella:
| Código | Significado |
|---|---|
request_timeout | No hubo respuesta dentro del timeout del cliente |
connection_error | Fallo de red |
invalid_response | Una respuesta 2xx que no era el JSON esperado |
invalid_argument | Nombre de base de datos inválido, consulta vacía o parámetros que no se pueden serializar |
missing_api_key | No se pasó ninguna key y NAMIDB_API_KEY no está definida |
http_error | Una respuesta de error que no viene de la API, por ejemplo de un proxy |