Skip to content

Errors

All NamiDB Cloud APIs return errors in one shape:

{"error": {"code": "plan_limit", "message": "…", "request_id": "…"}}
  • Branch on code. Codes are stable; messages are for people and may change.
  • Quote request_id (also in the x-request-id header) when you contact support.
  • Retry-After (seconds) comes with 429 and with 503 engine_starting.

The SDKs raise these as NamiDBError with the same code, status, request_id and retry_after.

Data API

These come from db.namidb.com over HTTP and MCP. Over Bolt, the same conditions are Bolt failures with the Neo4j code shown.

CodeStatusBoltMeaningWhat to do
unauthorized401Security.UnauthorizedThe key is missing, invalid, revoked or expiredCheck the key; create a new one if it was revoked or expired
database_not_in_scope403Security.ForbiddenThe key isn’t scoped to this databaseUse a key that covers it, or name a database in its scope
read_only_key403Security.ForbiddenA write was sent with a read-only keyUse a read-write key for writes
ip_not_allowed403Security.Forbidden, connection closedThe client address is outside the organization’s or the key’s IP allowlist; the message names the address and listAdd the address under API keys → IP allowlist
org_paused403Security.Forbidden, connection closedA Free organization paused after 7 days without activityResume it from the console
org_suspended403Security.Forbidden, connection closedNamiDB suspended the organization; the message carries the reasonContact support
access_banned403Security.Forbidden, connection closedNamiDB blocked the request for abuse: the client address is banned, or the organization or the key is (the message says which)Not retryable. If you think it is a mistake, contact info@namidb.com
database_not_found404No database with that nameCheck the name (GET /v1/databases)
query_not_found404The statement to cancel is no longer running (it finished, or the database is asleep)Nothing to do
payload_too_large413Request body over 2 MiBSend smaller batches
result_too_large413Result over 64 MiBLIMIT, paginate, or return fewer properties
plan_limit429Security.ForbiddenAn allowance is used up with the spend cap on, or the database is read-only after a downgradeUpgrade, turn the cap off, delete a database, or wait for the period to reset
rate_limited429TransientErrorToo many requests per second, concurrent queries or Bolt sessions, or too many invalid keys from this addressWait Retry-After and retry; smooth bursts
engine_starting503The database is waking from idleRetry after Retry-After (1 s); nothing ran
database_unavailable503The database is being restored, or its restore failedWait for ready, or delete a failed one
engine_unavailable502The engine could not be reachedRetry reads; for writes, check before retrying
control_plane_unavailable502The key could not be verified right nowRetry with backoff; nothing ran
bad_request400Malformed request (not JSON, no query, …)Fix the request
internal500Unexpected errorRetry later; contact support with the request id

Engine errors

Errors from the engine itself are passed through with its status, on HTTP, MCP and Bolt (with the engine’s Neo4j codes and, on Bolt 5.7, GQLSTATUS):

CodeStatusMeaning
parse_error400The Cypher doesn’t parse
plan_error, unsupported400Valid Cypher that NamiDB can’t plan, or a feature it doesn’t support
eval_error400A runtime error (type mismatch, division by zero, …)
constraint409A uniqueness or other constraint was violated
cancelled409The statement was cancelled (Activity tab or the cancel API)
row_cap413The result has more rows than one query may return
query_memory_limit413The query needs more working memory than your plan’s database size allows for one query. Over Bolt: Neo.ClientError.Statement.ResourceLimitExceeded
memory_pressure503The database is short of memory for queries right now, usually because several large queries are running at once. Over Bolt: Neo.TransientError.General.DatabaseUnavailable
timeout504Over the plan’s query timeout (10 s / 30 s / 60 s)

See the supported Cypher for what the engine accepts. Timeouts and row caps are not retryable as they are: narrow the query.

query_memory_limit (413) is not retryable either: the same query needs the same memory on every run, and a write that hits it commits nothing. Make each step hold less: filter and add LIMIT as early as you can, paginate with ORDER BY … SKIP … LIMIT or a key range, return fewer or smaller values, and aggregate (count(*), sum()) instead of returning or collect()ing raw rows. The limit grows with the plan’s database size.

memory_pressure (503) is transient: other queries are using the database’s query memory at the moment. Retry with exponential backoff. The Neo4j drivers retry it on their own, because it arrives as a TransientError. If it keeps happening, spread out your large queries or make them smaller, and consume or close Bolt results promptly: a result that hasn’t been read yet keeps its memory.

MCP

Over MCP, authentication and database errors are HTTP errors as above. Errors while running a tool (limits, Cypher errors) are tool results with isError: true and this error JSON as their text.

Management API

From app.namidb.com/api/v1:

CodeStatusMeaning
bad_request400Invalid input; details.field names the property (for example at for a point-in-time restore in the future)
reserved_name400backups, exports and tenants, and names starting with nmdbexp-, can’t be database names
unauthorized401Missing or invalid token (an API key sent here also gets this)
token_expired, token_revoked401The token expired or was revoked
insufficient_scope403The token’s scope doesn’t allow the operation
token_inactive403Its creator lost owner/admin access, was banned, or no longer meets the organization’s two-factor or SSO requirement; or the token that created it through the API no longer works
org_suspended403The organization is suspended
org_export_only403The organization is suspended or deleted: only exports work
ip_not_allowed403An export request or download from outside the organization’s IP allowlist
forbidden403Not allowed for another reason (for example, removing an owner)
plan_limit403Over a limit: databases, API keys, active management tokens (25), IP allowlist entries
aal2_required403The action needs a second factor
not_found, database_not_found404No such resource
conflict409The current state doesn’t allow it (for example, replying to a closed ticket)
name_taken409A database with that name exists
name_purging409A deleted database with that name is still being erased
database_unavailable409The database isn’t ready
backup_in_progress409A backup of this database is already running
backup_not_ready409The backup hasn’t succeeded, so it can’t be restored
export_in_progress409An export of this database is already running
no_backup, no_backup_before409Nothing to clone or restore from (at that time)
key_inactive, already_rotated409The key is revoked or expired, or was already rotated
already_member, already_invited, invite_closed409Invitation state conflicts
last_owner409The organization must keep an owner
idempotency_in_progress409A request with this Idempotency-Key is still running
export_expired410The export’s files were deleted after 7 days
payload_too_large413Body over 64 KiB
unsupported_media_type415Send Content-Type: application/json
lifetime_policy422The expiry is beyond the organization’s key lifetime policy
idempotency_key_reused422The key was used for a different request
rate_limited429Over 300 requests per minute, or an hourly budget; wait Retry-After
internal500Unexpected error
not_implemented501Reserved for an operation documented before it is available
control_plane_unavailable503Retry with backoff

SDK client-side codes

Raised by the SDKs before or without a response:

CodeMeaning
request_timeoutNo response within the client’s timeout
connection_errorNetwork failure
invalid_responseA 2xx response that wasn’t the expected JSON
invalid_argumentBad database name, empty query, or parameters that can’t be serialized
missing_api_keyNo key given and NAMIDB_API_KEY unset
http_errorA non-API error response, for example from a proxy