Troubleshooting

Start with the error's code. Every error from the API has one, and its docs_url links to the entry on Errors 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	401	You are not signed in, or the API token is missing, wrong, expired or revoked.
scope_missing	403	This API token does not have the scope this request needs.
session_only	403	This can only be done in the InfraNest app while signed in, not with an API token.
not_token_writable	403	This action is only available in the InfraNest app, not with an API token.
write_disabled	403	API write access is not switched on for this organization.
wrong_organization	403	This API token is bound to another organization.
token_ip_not_allowed	403	This API token cannot be used from this address.
test_token_required	403	This is a sandbox organization, and only its own test tokens work here.
test_token_sandbox_only	403	This is a test token, and it works only in its sandbox organization.
api_token_required	403	The MCP server takes an API token, not a signed-in session.
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	409	A sandbox belongs with an organization of your own.
organization_offline	409	This organization does not reach the internet, so nothing was looked up or sent.
permission_denied	403	Your role in this organization does not allow this.
forbidden	403	You are not allowed to do this.
organization_suspended	403	This organization is suspended, so nothing in it can be changed.
read_only_session	403	This session is read-only.
sso_required	403	This organization requires you to sign in with its single sign-on.
two_factor_setup_required	403	This organization requires two-factor authentication on your account.
password_reset_required	403	Your password has expired and must be changed.
email_verification_required	403	Your email address has not been confirmed yet.
plan_limit	402	Your plan does not include this, or its limit has been reached.
not_found	404	Nothing exists at this address, or you cannot see it.
method_not_allowed	405	This address does not accept that HTTP method.
conflict	409	This conflicts with something that already exists.
validation_failed	422	Some fields are missing or not valid.
unprocessable	422	The request could not be carried out as sent.
range_too_large	422	The time range is longer than this resolution allows.
rate_limited	429	Too many requests. Slow down and try again shortly.
idempotency_key_reused	422	This Idempotency-Key was already used for a different request.
idempotency_in_progress	409	A request with this Idempotency-Key is still being handled.
provider_refused	4xx / 502	The provider refused the request.
provider_rate_limited	429	The provider is limiting requests right now.
provider_unavailable	502	The provider could not be reached or is having problems.
maintenance	503	InfraNest is down for maintenance.
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.

Also check the header itself: Authorization: Bearer <token>, 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

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

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. In your sandbox, test tokens work on every plan. 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

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, writes always work. 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

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). 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

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.

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.
• 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

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 <token>. 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.

api_token_required

The MCP server takes an API token or an assistant's connection, never a browser session. 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 first if many requests fail at once.