Saltearse al contenido

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 cabecera x-request-id) cuando contactes a soporte.
  • Retry-After (en segundos) viene con 429 y con 503 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ódigoEstadoBoltSignificadoQué hacer
unauthorized401Security.UnauthorizedLa key falta, es inválida, está revocada o vencióRevisa la key; crea una nueva si se revocó o venció
database_not_in_scope403Security.ForbiddenLa key no tiene alcance sobre esta base de datosUsa una key que la cubra, o nombra una base de datos dentro de su alcance
read_only_key403Security.ForbiddenSe envió una escritura con una key de solo lecturaUsa una key de lectura y escritura para escribir
ip_not_allowed403Security.Forbidden, conexión cerradaLa 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 listaAgrega la dirección en API keys → IP allowlist
org_paused403Security.Forbidden, conexión cerradaUna organización Free se pausó después de 7 días sin actividadReanúdala desde la consola
org_suspended403Security.Forbidden, conexión cerradaNamiDB suspendió la organización; el mensaje incluye el motivoContacta a soporte
access_banned403Security.Forbidden, conexión cerradaNamiDB 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_found404No hay ninguna base de datos con ese nombreRevisa el nombre (GET /v1/databases)
query_not_found404La sentencia que querías cancelar ya no se está ejecutando (terminó, o la base de datos está dormida)Nada que hacer
payload_too_large413Cuerpo de la petición de más de 2 MiBEnvía lotes más pequeños
result_too_large413Resultado de más de 64 MiBLIMIT, pagina o devuelve menos propiedades
plan_limit429Security.ForbiddenSe agotó una cuota con el spend cap activado, o la base de datos es de solo lectura después de bajar de planSube de plan, desactiva el cap, elimina una base de datos o espera a que se reinicie el periodo
rate_limited429TransientErrorDemasiadas peticiones por segundo, consultas concurrentes o sesiones Bolt, o demasiadas keys inválidas desde esta direcciónEspera Retry-After y reintenta; suaviza las ráfagas
engine_starting503La base de datos está despertando de la inactividadReintenta después de Retry-After (1 s); no se ejecutó nada
database_unavailable503La base de datos se está restaurando, o su restauración fallóEspera a que esté ready, o elimina una que falló
engine_unavailable502No se pudo llegar al motorReintenta las lecturas; para las escrituras, verifica antes de reintentar
control_plane_unavailable502No se pudo verificar la key en este momentoReintenta con backoff; no se ejecutó nada
bad_request400Petición mal formada (no es JSON, falta query, …)Corrige la petición
internal500Error inesperadoReintenta 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ódigoEstadoSignificado
parse_error400El Cypher no se puede parsear
plan_error, unsupported400Cypher válido que NamiDB no puede planificar, o una funcionalidad que no soporta
eval_error400Un error en tiempo de ejecución (tipos incompatibles, división por cero, …)
constraint409Se violó un constraint de unicidad u otro
cancelled409La sentencia se canceló (pestaña Activity o la API de cancelación)
row_cap413El resultado tiene más filas de las que puede devolver una consulta
query_memory_limit413La 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_pressure503A 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
timeout504Superó 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ódigoEstadoSignificado
bad_request400Entrada inválida; details.field indica la propiedad (por ejemplo at para una restauración a un punto en el tiempo en el futuro)
reserved_name400backups, exports y tenants, y los nombres que empiezan con nmdbexp-, no pueden ser nombres de bases de datos
unauthorized401Token ausente o inválido (una API key enviada aquí también recibe esto)
token_expired, token_revoked401El token venció o fue revocado
insufficient_scope403El scope del token no permite la operación
token_inactive403Quien 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_suspended403La organización está suspendida
org_export_only403La organización está suspendida o eliminada: solo funcionan las exportaciones
ip_not_allowed403Una solicitud o descarga de exportación desde fuera de la IP allowlist de la organización
forbidden403No permitido por otro motivo (por ejemplo, quitar a un owner)
plan_limit403Se superó un límite: bases de datos, API keys, tokens de gestión activos (25), entradas de IP allowlists
aal2_required403La acción necesita un segundo factor
not_found, database_not_found404No existe ese recurso
conflict409El estado actual no lo permite (por ejemplo, responder a un ticket cerrado)
name_taken409Ya existe una base de datos con ese nombre
name_purging409Una base de datos eliminada con ese nombre todavía se está borrando
database_unavailable409La base de datos no está lista
backup_in_progress409Ya hay un backup de esta base de datos en ejecución
backup_not_ready409El backup no terminó con éxito, así que no se puede restaurar
export_in_progress409Ya hay una exportación de esta base de datos en ejecución
no_backup, no_backup_before409No hay nada desde lo cual clonar o restaurar (en ese momento)
key_inactive, already_rotated409La key está revocada o vencida, o ya se rotó
already_member, already_invited, invite_closed409Conflictos en el estado de la invitación
last_owner409La organización tiene que conservar un owner
idempotency_in_progress409Una petición con este Idempotency-Key todavía se está ejecutando
export_expired410Los archivos de la exportación se eliminaron después de 7 días
payload_too_large413Cuerpo de más de 64 KiB
unsupported_media_type415Envía Content-Type: application/json
lifetime_policy422El vencimiento supera la política de vida útil de keys de la organización
idempotency_key_reused422La key se usó para una petición distinta
rate_limited429Más de 300 peticiones por minuto, o se agotó un presupuesto por hora; espera Retry-After
internal500Error inesperado
not_implemented501Reservado para una operación documentada antes de estar disponible
control_plane_unavailable503Reintenta con backoff

Códigos del lado del cliente en los SDKs

Los lanzan los SDKs antes de recibir una respuesta o sin ella:

CódigoSignificado
request_timeoutNo hubo respuesta dentro del timeout del cliente
connection_errorFallo de red
invalid_responseUna respuesta 2xx que no era el JSON esperado
invalid_argumentNombre de base de datos inválido, consulta vacía o parámetros que no se pueden serializar
missing_api_keyNo se pasó ninguna key y NAMIDB_API_KEY no está definida
http_errorUna respuesta de error que no viene de la API, por ejemplo de un proxy