Skip to Content

API

Errors

Every error the Improve API returns, as JSON problem details with a stable code and a hint.

7 min read

Every non-2xx response from /api/* and /config/* is JSON in the RFC 9457 problem details 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.

{
	"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."
}
FieldMeaning
typeLink to the section on this page for the error code
titleShort, fixed description of the error code
statusThe HTTP status code, repeated
detailWhat went wrong with this specific request
codeStable identifier to branch on; one of the codes below
hintWhat 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

invalid_json

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

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

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.

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.

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

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

401. An agent API 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

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

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

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

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

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

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

403. Your role in the organization doesn't allow this action, for example a reader creating a test. See roles. Ask an admin of the organization for more access.

product_disabled

403. An admin of the organization has disabled Improve for it, in the organization's settings on 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

403. The environment is reviewed: only admins change what it serves. Ask for the change instead (askForChange), or an admin makes it. See Approvals.

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

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

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

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

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

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

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, or wait for the new month.

forbidden

403. The request's Origin is not in the environment's Allowed origins (on the space’s page on www.obelism.studio), or the token header is not a valid API token for the environment. See Security.

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's account endpoints limit attempts per email address, reset token or user, and state the limit in the same RateLimit-Policy header.

ingest_failed

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

not_found

404. No API endpoint exists at this path. See the OpenAPI spec for the available endpoints.

method_not_allowed

405. The endpoint exists but not for this HTTP method, for example GET /api/log. See the OpenAPI spec.

internal_error

500. An unexpected server error. Retry later; if it keeps failing, email improve@obelism.studio.

On this page

Marks in the margin

  • Note
  • Watch out
  • Updated

Scribes marked doubtful lines in the margin. That practice is called obelism.