# Troubleshooting Find your symptom, check the likely cause, then follow the fix. For how ATLAS reports errors, see [Errors](https://docs.atlas.ilionx.dev/reference/errors.md). ## Before you begin Note what you see: the HTTP status, the `error.code` or `type` in the response body, or the title of the page in the web app. The gateway doesn't say _why_ it rejected a key, so work through the causes in order. ## Calling the gateway | You see (see [Errors](https://docs.atlas.ilionx.dev/reference/errors.md#common-gateway-codes) for meanings) | What to do | | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` `authentication_required` | Check the header: `Authorization: Bearer atl_sk_…` for OpenAI clients, or `x-api-key` for Anthropic clients. Sending both with different values is refused. Open **My API keys**, check that the key exists and hasn't expired, or create a new one. | | `403` `no_acting_context` | Open **My API keys**, choose **Switch Context** on the key and pick a **Context**. See [create and manage API keys](https://docs.atlas.ilionx.dev/guides/user/api-keys-create-and-manage.md). | | `403` `organization_suspended` | Ask your organisation's Admin. | | `403` `project_archived` | Ask a project manager or Admin to reactivate the project, or move the key to another context. | | `403` `provider_disabled` or `provider_access_denied` | Ask an Admin to check that the provider is enabled. | | `404` `model_not_found` | Use the full reference `provider-slug/model-slug`, not a bare name. List what you can use with `GET /gateway/openai/v1/models`. | | `404` `project_has_no_models` | Ask a project manager to add models. See [configure a project's models](https://docs.atlas.ilionx.dev/guides/admin/projects-configure-models-and-ai-settings.md). | | `404` with no error body, or an HTML page | Use `https:///gateway/openai/v1` for OpenAI clients and `https:///gateway/anthropic` for Anthropic clients. The `/gateway` segment is missing. | | `429` `budget_exceeded` | Check **My usage**, then ask the owner of the budget to raise it. See [set a space budget](https://docs.atlas.ilionx.dev/guides/admin/budget-and-cost-set-a-space-budget.md) and [fund a project](https://docs.atlas.ilionx.dev/guides/admin/projects-fund-a-project.md). | | `402` `billing_error` (Anthropic-compatible clients) | The same as `429` `budget_exceeded`. A used-up budget returns `402` on Anthropic addresses. | | `429` `provider_rate_limited` | Wait for the seconds in the `Retry-After` header, then retry. | | `400` `invalid_request` or `model_not_supported_for_endpoint` | Check the request body, and use an endpoint the model supports. | | `413` `request_too_large` | Send less content. | | `500`, `502`, `503`, `504`, `529` | Retry after a short wait. If it persists, ask an Admin to check that the provider is reachable and its credentials are valid. Then ask your ilionx contact, with the details under [Getting help](https://docs.atlas.ilionx.dev/guides/troubleshooting.md#getting-help). | Changes to keys, memberships, budgets and model access reach the gateway within seconds. A request sent straight after a change can still see the old state. ## Signing in and using the web app | You see | Likely cause | What to do | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Organization Not Recognized** | Your email domain is not registered to an organisation. | Ask your organisation's Admin to request your email domain from your ilionx contact. See [email domains](https://docs.atlas.ilionx.dev/concepts/organisations.md#email-domains). | | **Email Address Required** | Your identity provider did not share an email address. | Ask your identity-provider administrator to release the email claim. | | **Organization Suspended** | Your organisation is suspended. | Ask your organisation's Admin. | | "Your organisation hasn't given you access to Atlas" | Your account has no role assigned through the organisation's identity provider. | Ask your identity-provider administrator to add you to a group mapped to an ATLAS role: Admin or Member for access, plus Account Manager or Auditor if you need those. The Owner role is never taken from a group. | | "Your organisation's sign-in didn't share your groups with Atlas" | The identity provider sent too many groups to fit in the token. | Ask your identity-provider administrator to limit the groups claim to assigned security groups. See [configure Microsoft Entra ID sign-in](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md). | | "Your account was deactivated" or "Access is managed by your organisation's directory" | Your account was disabled, or is not provisioned in the organisation's directory. | Ask your identity-provider administrator. | | "Your organisation has reached its seat limit" | The contract allows no more active people. | Ask an Admin to free a seat, or ask your ilionx contact to raise the limit. | | **Access Refused** | A general refusal. | Note the code shown and the time, then give both to your Admin. | | An error with an `ERR-nnnn` code | The server refused an action. | Look the code up in the error catalogue for the cause and fix. See [Errors](https://docs.atlas.ilionx.dev/reference/errors.md). | ## Keys, projects and models | Symptom | Cause | What to do | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A key stopped working on a given date | The key expired. Your organisation may cap how long keys last. | Create a new key. Admins can review the cap in [API key lifetime](https://docs.atlas.ilionx.dev/guides/admin/spaces-manage-policies.md#cap-api-key-lifetime). | | A key that worked now fails with `no_acting_context` | You were removed from the space or project it acted under, or the project was deleted. The key remains but its context is cleared. | Ask to be re-added, or choose another **Context**. | | A project key stopped working after its project was deleted | Deleting a project also deletes its keys. | Create a key under another project. | | A model is listed but "not found" when called | The model was deactivated, or a space restriction blocks it. | Ask an Admin to reactivate the model or lift the restriction. See [restrict models for a space](https://docs.atlas.ilionx.dev/guides/admin/spaces-manage-policies.md#restrict-models-for-a-space). | | A new model does not appear | It is not added to your project, not offered to your space, or the change hasn't reached the gateway yet (it takes a few seconds). | Check the project's **Models** tab and the space's **Models** tab. | | A funded project refuses all traffic | It has no remaining funds. | Add funds. See [fund a project](https://docs.atlas.ilionx.dev/guides/admin/projects-fund-a-project.md). | ## Getting help If none of this fixes it, ask your organisation's Admin or your ilionx contact. Give them the status, the error code, the `atlas-request-id` response header if there is one, and the time of the request. ## Related - [Errors](https://docs.atlas.ilionx.dev/reference/errors.md) - [Quickstart](https://docs.atlas.ilionx.dev/getting-started/quickstart.md) - [User guides](https://docs.atlas.ilionx.dev/guides/user.md) - [Administrator guides](https://docs.atlas.ilionx.dev/guides/admin.md)