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 thex-request-idheader) when you contact support. Retry-After(seconds) comes with429and with503 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.
| Code | Status | Bolt | Meaning | What to do |
|---|---|---|---|---|
unauthorized | 401 | Security.Unauthorized | The key is missing, invalid, revoked or expired | Check the key; create a new one if it was revoked or expired |
database_not_in_scope | 403 | Security.Forbidden | The key isn’t scoped to this database | Use a key that covers it, or name a database in its scope |
read_only_key | 403 | Security.Forbidden | A write was sent with a read-only key | Use a read-write key for writes |
ip_not_allowed | 403 | Security.Forbidden, connection closed | The client address is outside the organization’s or the key’s IP allowlist; the message names the address and list | Add the address under API keys → IP allowlist |
org_paused | 403 | Security.Forbidden, connection closed | A Free organization paused after 7 days without activity | Resume it from the console |
org_suspended | 403 | Security.Forbidden, connection closed | NamiDB suspended the organization; the message carries the reason | Contact support |
access_banned | 403 | Security.Forbidden, connection closed | NamiDB 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_found | 404 | No database with that name | Check the name (GET /v1/databases) | |
query_not_found | 404 | The statement to cancel is no longer running (it finished, or the database is asleep) | Nothing to do | |
payload_too_large | 413 | Request body over 2 MiB | Send smaller batches | |
result_too_large | 413 | Result over 64 MiB | LIMIT, paginate, or return fewer properties | |
plan_limit | 429 | Security.Forbidden | An allowance is used up with the spend cap on, or the database is read-only after a downgrade | Upgrade, turn the cap off, delete a database, or wait for the period to reset |
rate_limited | 429 | TransientError | Too many requests per second, concurrent queries or Bolt sessions, or too many invalid keys from this address | Wait Retry-After and retry; smooth bursts |
engine_starting | 503 | The database is waking from idle | Retry after Retry-After (1 s); nothing ran | |
database_unavailable | 503 | The database is being restored, or its restore failed | Wait for ready, or delete a failed one | |
engine_unavailable | 502 | The engine could not be reached | Retry reads; for writes, check before retrying | |
control_plane_unavailable | 502 | The key could not be verified right now | Retry with backoff; nothing ran | |
bad_request | 400 | Malformed request (not JSON, no query, …) | Fix the request | |
internal | 500 | Unexpected error | Retry 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):
| Code | Status | Meaning |
|---|---|---|
parse_error | 400 | The Cypher doesn’t parse |
plan_error, unsupported | 400 | Valid Cypher that NamiDB can’t plan, or a feature it doesn’t support |
eval_error | 400 | A runtime error (type mismatch, division by zero, …) |
constraint | 409 | A uniqueness or other constraint was violated |
cancelled | 409 | The statement was cancelled (Activity tab or the cancel API) |
row_cap | 413 | The result has more rows than one query may return |
query_memory_limit | 413 | The query needs more working memory than your plan’s database size allows for one query. Over Bolt: Neo.ClientError.Statement.ResourceLimitExceeded |
memory_pressure | 503 | The database is short of memory for queries right now, usually because several large queries are running at once. Over Bolt: Neo.TransientError.General.DatabaseUnavailable |
timeout | 504 | Over 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:
| Code | Status | Meaning |
|---|---|---|
bad_request | 400 | Invalid input; details.field names the property (for example at for a point-in-time restore in the future) |
reserved_name | 400 | backups, exports and tenants, and names starting with nmdbexp-, can’t be database names |
unauthorized | 401 | Missing or invalid token (an API key sent here also gets this) |
token_expired, token_revoked | 401 | The token expired or was revoked |
insufficient_scope | 403 | The token’s scope doesn’t allow the operation |
token_inactive | 403 | Its 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_suspended | 403 | The organization is suspended |
org_export_only | 403 | The organization is suspended or deleted: only exports work |
ip_not_allowed | 403 | An export request or download from outside the organization’s IP allowlist |
forbidden | 403 | Not allowed for another reason (for example, removing an owner) |
plan_limit | 403 | Over a limit: databases, API keys, active management tokens (25), IP allowlist entries |
aal2_required | 403 | The action needs a second factor |
not_found, database_not_found | 404 | No such resource |
conflict | 409 | The current state doesn’t allow it (for example, replying to a closed ticket) |
name_taken | 409 | A database with that name exists |
name_purging | 409 | A deleted database with that name is still being erased |
database_unavailable | 409 | The database isn’t ready |
backup_in_progress | 409 | A backup of this database is already running |
backup_not_ready | 409 | The backup hasn’t succeeded, so it can’t be restored |
export_in_progress | 409 | An export of this database is already running |
no_backup, no_backup_before | 409 | Nothing to clone or restore from (at that time) |
key_inactive, already_rotated | 409 | The key is revoked or expired, or was already rotated |
already_member, already_invited, invite_closed | 409 | Invitation state conflicts |
last_owner | 409 | The organization must keep an owner |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still running |
export_expired | 410 | The export’s files were deleted after 7 days |
payload_too_large | 413 | Body over 64 KiB |
unsupported_media_type | 415 | Send Content-Type: application/json |
lifetime_policy | 422 | The expiry is beyond the organization’s key lifetime policy |
idempotency_key_reused | 422 | The key was used for a different request |
rate_limited | 429 | Over 300 requests per minute, or an hourly budget; wait Retry-After |
internal | 500 | Unexpected error |
not_implemented | 501 | Reserved for an operation documented before it is available |
control_plane_unavailable | 503 | Retry with backoff |
SDK client-side codes
Raised by the SDKs before or without a response:
| Code | Meaning |
|---|---|
request_timeout | No response within the client’s timeout |
connection_error | Network failure |
invalid_response | A 2xx response that wasn’t the expected JSON |
invalid_argument | Bad database name, empty query, or parameters that can’t be serialized |
missing_api_key | No key given and NAMIDB_API_KEY unset |
http_error | A non-API error response, for example from a proxy |