# Errors (/docs/api/errors)

Every non-`2xx` response from `/api/*` and `/config/*` is JSON in the [RFC 9457 problem details](https://www.rfc-editor.org/rfc/rfc9457) format, with `Content-Type: application/problem+json`. That includes paths that don't exist and unsupported HTTP methods, so a client never has to parse an HTML error page.

```json
{
	"type": "https://improve.obelism.studio/docs/api/errors#forbidden",
	"title": "The request origin is not allow-listed and no valid token was sent.",
	"status": 403,
	"detail": "This origin or token is not allowed for this environment.",
	"code": "forbidden",
	"hint": "Add the site origin to Allowed origins for this environment, or send a valid `token` header from a server."
}
```

| Field    | Meaning                                                 |
| -------- | ------------------------------------------------------- |
| `type`   | Link to the section on this page for the error code     |
| `title`  | Short, fixed description of the error code              |
| `status` | The HTTP status code, repeated                          |
| `detail` | What went wrong with this specific request              |
| `code`   | Stable identifier to branch on; one of the codes below  |
| `hint`   | What to change before retrying (present on most errors) |

Errors from `POST /api/log` also include `success: false`, which older clients check. A `429` also sends `Retry-After` and `RateLimit` headers.

The datafile endpoint keeps one exception for SDK compatibility: when the `organizationId`, `environment` or `status` path segment is invalid, it answers `200` with an empty datafile `{}`, so SDKs fall back to their default values instead of throwing.

## Error codes [#error-codes]

### invalid_json [#invalid_json]

`400`. The request body is not valid JSON. Send a JSON object with `Content-Type: application/json`.

### payload_too_large [#payload_too_large]

`413`. The request body exceeds the size limit (8 KB for `/api/log`). Send one analytic per request and keep `params` small.

### invalid_request [#invalid_request]

`400`. A required field is missing, has the wrong type, or is outside its allowed values. `detail` names the field. Check the body against the [OpenAPI spec](/openapi.json).

### unsupported_api_version [#unsupported_api_version]

`400`. The request sent an `Api-Version` header naming a version this API doesn't serve. The only version is `1`. Send `Api-Version: 1` or leave the header out. See [Versioning](/docs/api/versioning).

### reserved_event_name [#reserved_event_name]

`400`. Event names starting with `gtm.` are Google Tag Manager internals and are not stored. Rename the event, or filter `gtm.*` events out before sending.

### unknown_organization [#unknown_organization]

`404`. The `organizationId` (or `spaceId`) could not be resolved, or the space belongs to another organization. Copy them from Implementation on the Settings page in the dashboard. `/api/log` and the datafile also answer it for an Organization that was deleted (`detail`: "This organization was deleted."): nothing more is stored or served for it. The datafile caches this answer at the edge for 30 seconds.

### unauthorized [#unauthorized]

`401`. An [agent API](/docs/api/agents) endpoint needs a bearer token and none was sent, or it is invalid or expired. Sign in again with `POST /api/agent/auth/sign-in` and send `Authorization: Bearer <token>`.

### invalid_credentials [#invalid_credentials]

`401`. The email and password do not match an account. The response is the same whether the email is unknown or the password is wrong.

### password_reset_required [#password_reset_required]

`401`. The account's password was stored in a format that is no longer supported. Reset it at [www.obelism.studio/forgot-password](https://www.obelism.studio/forgot-password), then sign in again.

### two_factor_required [#two_factor_required]

`401` from sign-in, `400` from reset-password. The account has two-factor authentication on, and the request had no `code`. Send it again with `code`: the current 6-digit code from the authenticator app, or the recovery code.

### invalid_two_factor_code [#invalid_two_factor_code]

`401` from sign-in, `400` from reset-password. The `code` is not the authenticator app's current code, that code was already used, or it is not the recovery code. Wait for the next code. Five codes per account per 15 minutes.

### invalid_verification_code [#invalid_verification_code]

`400`. The email verification code is wrong or has expired. Codes are valid for 4 hours. Sign in again to get a new one by email.

### invalid_reset_token [#invalid_reset_token]

`400`. The password reset token is wrong, has expired or was already used. A token is valid for 1 hour, and requesting a new reset email replaces the previous token. Request a new one with `POST /api/agent/auth/forgot-password`.

### insufficient_role [#insufficient_role]

`403`. Your role in the organization doesn't allow this action, for example a `reader` creating a test. See [roles](/docs/api/agents/organizations#roles). Ask an admin of the organization for more access.

### product_disabled [#product_disabled]

`403`. An admin of the organization has disabled Improve for it, in the organization's settings on [www.obelism.studio](https://www.obelism.studio). The dashboard, MCP and this API refuse it, whatever your role. Tests and flags keep being served to visitors, and analytics keep being collected. Ask an admin to enable Improve again.

### review_required [#review_required]

`403`. The environment is reviewed: only admins change what it serves. Ask for the change instead (`askForChange`), or an admin makes it. See [Approvals](/docs/guides/approvals).

### second_factor_required [#second_factor_required]

`403`. The organization requires a second factor and this sign-in or connection was made without one. Sign in on www with a passkey or an authenticator code, then reconnect.

### production_protected [#production_protected]

`403`. The agent API and MCP don't add, change, rotate the secret of or delete a webhook in the `production` environment: a webhook sends production changes somewhere, and an agent could be talked into pointing one elsewhere by what it reads. A person with the developer or admin role does it in the dashboard, under Settings → Webhooks. Listing webhooks and their deliveries, sending a test and sending a delivery again still work in production, and every operation works in `develop` and `staging`. Turning approvals **off** in production is refused the same way: an agent may turn them on, never off.

### resource_not_found [#resource_not_found]

`404`. The test, flag, audience or other resource in the path doesn't exist in this organization and environment. Tests, flags and audiences belong to one environment, so check you are in the right one.

### slug_conflict [#slug_conflict]

`409`. Copying tests to another environment found tests with the same slug there, so nothing was copied. The problem has a `conflicts` array with the `testId`, `name` and `slug` of each. Send the request again with `"overwrite": true` to replace them, or leave them out.

### conflict [#conflict]

`409`. The resource changed since it was read (a save with an old `baseRevision`), or one like it already exists (a second connection for the same deployment in a space). Read it again, apply the change to what is there now, and send it with its current revision.

### usage_limit_reached [#usage_limit_reached]

`402`. The organization is past its event pool and its plan's buffer on top, so test results are frozen at their last calculation. Events keep being recorded, and results catch up once the plan is upgraded or the next period starts. Reading results still works.

### usage_limit_exceeded [#usage_limit_exceeded]

`403`. The organization is past its event pool and its plan's buffer on top, so Improve is read-only until the new month or a bigger plan: creating and changing tests, flags and audiences is refused, in the dashboard, MCP and this API. Tests and flags keep being served to visitors. Change the plan on [www.obelism.studio](https://www.obelism.studio), or wait for the new month.

### forbidden [#forbidden]

`403`. The request's `Origin` is not in the environment's Allowed origins (on the space’s page on [www.obelism.studio](https://www.obelism.studio)), or the `token` header is not a valid API token for the environment. See [Security](/docs/api#security).

### rate_limited [#rate_limited]

`429`. Too many requests in the current window. Wait for the `Retry-After` seconds before retrying. Browser (Origin) requests to the datafile are limited to 600 per minute per IP, and the `RateLimit-Policy` header on every browser response states the limit: cache the datafile, or fetch it server-side with a valid `token` header, which is exempt. Every datafile request is also limited at the edge to 100 per 10 seconds per IP; that `429` is `application/json` without `Retry-After`, so wait 10 seconds. The [agent API](/docs/api/agents)'s account endpoints limit attempts per email address, reset token or user, and state the limit in the same `RateLimit-Policy` header.

### ingest_failed [#ingest_failed]

`400`. The analytic was valid but could not be queued. Retry the request later.

### not_found [#not_found]

`404`. No API endpoint exists at this path. See the [OpenAPI spec](/openapi.json) for the available endpoints.

### method_not_allowed [#method_not_allowed]

`405`. The endpoint exists but not for this HTTP method, for example `GET /api/log`. See the [OpenAPI spec](/openapi.json).

### internal_error [#internal_error]

`500`. An unexpected server error. Retry later; if it keeps failing, email [improve@obelism.studio](mailto:improve@obelism.studio).
