> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Troubleshooting: managing databases

Last updated 2 November 2026

Look up the answer the CLI or the Management API gave when it refused to create, list, change or delete a database: why, whether to send it again, and what to do.

The answer names its code in `code`, and `errors` names each field it refused.

| Answer | When | Send again | What to do |
| --- | --- | --- | --- |
| `401 exchange_required` | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. |
| `401 unauthenticated` | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. |
| `402 payment_required` | The account’s balance is zero, so nothing new is created. | No | Add credit on Usage & billing, then send the request again. |
| `403 forbidden` | The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may. | No | Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. |
| `404 not_found` | No live resource of the key’s account has that name or id, or the key is narrowed away from it. | No | Check the name, and that the key belongs to the account that holds it; list the resources to see what exists. |
| `409 conflict` | The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. `detail` says which, and `errors` names the field. | No | Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. |
| `409 managed_by_machine` | The database belongs to a Machine: it is deleted with its Machine, and it is never deleted or made public or private by itself. | No | Delete the Machine to delete its database. |
| `412 precondition_failed` | If-Match does not name the resource’s current ETag: it changed since you read it. Nothing changed. | No | Read the resource again, check that the change still applies, and send it with the new ETag. |
| `422 validation_error` | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. |
| `429 rate_limited` | The key or the account sent more requests than its rate allows. | After Retry-After | Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. |
| `500 internal_error` | Tonbo failed while answering the request. | Yes, the same request | Send the request again. If it keeps failing, talk to us and quote the answer’s `request_id`. |
| `503 region_unavailable` | The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After. | After Retry-After | Send the request again after Retry-After; if `detail` says the region takes no new resource of this kind, name another region. |