> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ev-cloud.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ev-cloud.ai/_mcp/server.

# Troubleshooting

| Symptom                                                                                                                 | Cause                                                                                                                 | Fix                                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401 Missing bearer token`                                                                                              | No token was sent, or it is not exported in the shell that runs your code.                                            | Check `echo $EVCLOUD_TOKEN`.                                                                                                     |
| MCP client never opens the browser to sign in                                                                           | The API host has no `MCP_OAUTH_ISSUER` or `MCP_PUBLIC_URL`, so `/mcp` names no sign-in server.                        | Set both on the deployment, or send an SDK token in the `Authorization` header. See [MCP server](/agents/mcp-server#host-it).    |
| `401 invalid token`                                                                                                     | The token is malformed, expired, signed with another key, or has no expiry.                                           | Use a valid SDK token that expires, or sign in with `evcloud-cli auth login`. See [Authentication](/get-started/authentication). |
| `403 admin role required`                                                                                               | The operation needs an organization admin.                                                                            | Use a token from an admin.                                                                                                       |
| `404` for an id you know exists                                                                                         | The id belongs to another organization.                                                                               | Use a token from the organization that owns it.                                                                                  |
| `409` when you create a location or EVSE                                                                                | An object with that uid already exists, possibly in another location. The message names the owner.                    | Use a unique uid.                                                                                                                |
| `409` "charge point 'X' is offline" on a CPO command (reboot, reset, remote start or stop, unlock, change availability) | The charge point has never connected to the OCPP gateway.                                                             | Connect the charger, then send the command again.                                                                                |
| `422`                                                                                                                   | The request does not match the schema. The response lists each invalid field.                                         | Fix the fields named in `detail`.                                                                                                |
| `429`                                                                                                                   | Too many requests per minute for your organization (eMSP routes).                                                     | Wait for the number of seconds in `Retry-After`.                                                                                 |
| `502` "… gateway unreachable"                                                                                           | EV Cloud could not reach the gateway behind the route.                                                                | Retry later. If it persists, the gateway is down or EV Cloud points at the wrong gateway URL.                                    |
| `502` with a gateway message                                                                                            | The gateway behind the API failed. The message reads `<gateway> error (<status>): <detail>`, with credentials masked. | Read the detail. Retry later if it points to a temporary failure.                                                                |
| SDK error "relative URL without a base", or a missing `base_url`                                                        | The client was created without your EV Cloud host.                                                                    | Pass `environment` (TypeScript), `base_url` (Python) or `--base-url` (CLI).                                                      |

## Still stuck?

* Check that the API is up: `GET https://api.ev-cloud.ai/health`.
* [Open an issue](https://github.com/ev-cloudx/evcloud-sdk/issues) with the request time, the operation and the response body. Never send your token.