# Troubleshooting Start with the error's `code`. Every error from the API has one, and its `docs_url` links to the entry on [Errors](errors.md) that says what it means, why it usually happens and what to do. The problems below are the ones that are not a single code: a token that stopped working, a script that slows down, an assistant that will not connect. ## Every error code | Code | Status | What it means | |---|---|---| | [`unauthenticated`](/errors#unauthenticated) | 401 | You are not signed in, or the API token is missing, wrong, expired or revoked. | | [`scope_missing`](/errors#scope_missing) | 403 | This API token does not have the scope this request needs. | | [`session_only`](/errors#session_only) | 403 | This can only be done in the InfraNest app while signed in, not with an API token. | | [`not_token_writable`](/errors#not_token_writable) | 403 | This action is only available in the InfraNest app, not with an API token. | | [`write_disabled`](/errors#write_disabled) | 403 | API write access is not switched on for this organization. | | [`wrong_organization`](/errors#wrong_organization) | 403 | This API token is bound to another organization. | | [`token_ip_not_allowed`](/errors#token_ip_not_allowed) | 403 | This API token cannot be used from this address. | | [`test_token_required`](/errors#test_token_required) | 403 | This is a sandbox organization, and only its own test tokens work here. | | [`test_token_sandbox_only`](/errors#test_token_sandbox_only) | 403 | This is a test token, and it works only in its sandbox organization. | | [`api_token_required`](/errors#api_token_required) | 403 | The MCP server takes an API token, not a signed-in session. | | [`sandbox_personal`](/errors#sandbox_personal) | 409 | A sandbox is personal: nobody can be invited into it, and it cannot be subscribed or handed to someone else. | | [`sandbox_needs_organization`](/errors#sandbox_needs_organization) | 409 | A sandbox belongs with an organization of your own. | | [`organization_offline`](/errors#organization_offline) | 409 | This organization does not reach the internet, so nothing was looked up or sent. | | [`permission_denied`](/errors#permission_denied) | 403 | Your role in this organization does not allow this. | | [`forbidden`](/errors#forbidden) | 403 | You are not allowed to do this. | | [`organization_suspended`](/errors#organization_suspended) | 403 | This organization is suspended, so nothing in it can be changed. | | [`read_only_session`](/errors#read_only_session) | 403 | This session is read-only. | | [`sso_required`](/errors#sso_required) | 403 | This organization requires you to sign in with its single sign-on. | | [`two_factor_setup_required`](/errors#two_factor_setup_required) | 403 | This organization requires two-factor authentication on your account. | | [`password_reset_required`](/errors#password_reset_required) | 403 | Your password has expired and must be changed. | | [`email_verification_required`](/errors#email_verification_required) | 403 | Your email address has not been confirmed yet. | | [`plan_limit`](/errors#plan_limit) | 402 | Your plan does not include this, or its limit has been reached. | | [`not_found`](/errors#not_found) | 404 | Nothing exists at this address, or you cannot see it. | | [`method_not_allowed`](/errors#method_not_allowed) | 405 | This address does not accept that HTTP method. | | [`conflict`](/errors#conflict) | 409 | This conflicts with something that already exists. | | [`validation_failed`](/errors#validation_failed) | 422 | Some fields are missing or not valid. | | [`unprocessable`](/errors#unprocessable) | 422 | The request could not be carried out as sent. | | [`range_too_large`](/errors#range_too_large) | 422 | The time range is longer than this resolution allows. | | [`rate_limited`](/errors#rate_limited) | 429 | Too many requests. Slow down and try again shortly. | | [`idempotency_key_reused`](/errors#idempotency_key_reused) | 422 | This Idempotency-Key was already used for a different request. | | [`idempotency_in_progress`](/errors#idempotency_in_progress) | 409 | A request with this Idempotency-Key is still being handled. | | [`provider_refused`](/errors#provider_refused) | 4xx / 502 | The provider refused the request. | | [`provider_rate_limited`](/errors#provider_rate_limited) | 429 | The provider is limiting requests right now. | | [`provider_unavailable`](/errors#provider_unavailable) | 502 | The provider could not be reached or is having problems. | | [`maintenance`](/errors#maintenance) | 503 | InfraNest is down for maintenance. | | [`server_error`](/errors#server_error) | 500 | Something went wrong on our side. | Quote the error's `reference` (also the `X-Request-Id` header) when you contact support. It finds your request in our logs. ## Token problems ### It worked yesterday and answers `unauthenticated` today The token has probably expired. New tokens expire after 90 days unless you chose another period, and you get an email a week before. Open **My account → Developer**, find the token and select **Renew**: it keeps its value and scopes, so nothing needs updating. A revoked token cannot be renewed; create a new one. See [Expiry](tokens-and-scopes.md#expiry). Also check the header itself: `Authorization: Bearer `, with the whole token including the part before the `|`. A shell variable that is empty in CI sends `Bearer ` and nothing else. ### `wrong_organization` The token was made for one organization and the address names another. A token is bound to the organization it was created in unless you chose **all my organizations**. Check the number after `/organizations/` in your script, or create a token in the organization you mean. [`wrong_organization`](errors.md#wrong_organization) ### `token_ip_not_allowed` The token has an address list, and the request came from somewhere else. Common causes: - **A CI runner.** Hosted runners change address on every run; an address list does not suit them. - **IPv6.** Your machine may reach the API over IPv6 while you listed its IPv4 address. Add both, or a range. - **A VPN or a proxy**, which changes the address the API sees. Change the list under **My account → Developer**, on the token. [`token_ip_not_allowed`](errors.md#token_ip_not_allowed) ### `plan_limit` when creating a token, or `api.read` / `api.write` in the error API tokens come with the Pro plan and up; Free includes the read-only assistant only. See which plan includes what on [Limits](limits.md#what-each-plan-includes). In your [sandbox](sandbox.md), test tokens work on every plan. [`plan_limit`](errors.md#plan_limit) ### `scope_missing` The error's `required` field names the scope that is missing. Tokens cannot gain scopes later: create a new token with it, and give each token only what it needs. [`scope_missing`](errors.md#scope_missing) ### `write_disabled` Writes through the API are switched on per organization. Reads keep working while they are off. Ask an owner of the organization. In the [sandbox](sandbox.md), writes always work. [`write_disabled`](errors.md#write_disabled) ### `test_token_required` or `test_token_sandbox_only` Test tokens (`in_test_…`) work only in your sandbox, and live tokens never work there. Use a token made in the organization you are calling. [`test_token_required`](errors.md#test_token_required) ## Slowing down: `429 rate_limited` Each token has budgets: 300 requests and 60 changes a minute, and 1,000 changes an hour, by default (see [Limits](limits.md)). The error's `limit_key` says which one ran out. Every response carries `X-RateLimit-Remaining`; when it reaches zero, wait the seconds in `Retry-After` before the next request. Do not retry in a tight loop: the waiting time does not shorten. A script that has to change many records can spread them out, or use an endpoint that takes many at once. [`rate_limited`](errors.md#rate_limited) ## A retry created something twice Send an `Idempotency-Key` header with every `POST` and keep the same key when you retry. The API then returns the first answer instead of doing it again. See [Retries and dry runs](retries-and-dry-runs.md). ## Assistant and MCP connection problems ### Claude or ChatGPT will not connect - **The address is wrong.** The connector's URL is `https://api.infranest.io/mcp`, nothing more. See [Connect Claude and ChatGPT](ai/claude-and-chatgpt.md). - **You did not allow it.** The assistant gets access only after you pick an organization and select **Allow** on InfraNest's consent page. Connect again. - **It worked and then stopped.** An assistant that has not been used for 30 days has to be connected again, and one removed under **My account → Authorized apps** loses access at once. Connect it again. ### It answers about the wrong organization Connected with InfraNest, an assistant reads only the organization you picked on the consent page. Remove it under **My account → Authorized apps**, connect again and pick the other one. With a token, ask it to run `list_organizations` and name the one you mean, or create the token in the right organization. ### It says a scope is missing The token or the connection does not include that area. Give the token the read scope it names, or reconnect and pick an organization where your role allows it. [`scope_missing`](errors.md#scope_missing) ### Cursor, VS Code or Claude Code answers `401` The editor sent no token, or an empty one. The token goes in the header `Authorization: Bearer `. When the configuration reads it from `INFRANEST_TOKEN`, that variable must be set where the editor starts, not only in your terminal. See [Connect with a token](ai-assistants.md#connect-with-a-token). ### `api_token_required` The MCP server takes an API token or an assistant's connection, never a browser session. [`api_token_required`](errors.md#api_token_required) ### An answer is cut off One answer is at most 80,000 characters. Ask the assistant to use the tool's filters, or a later page. ## Still stuck Use **Report a problem** at the bottom of any page, or email support with the error's `reference`. Check [status.infranest.io](https://status.infranest.io) first if many requests fail at once.