Errors
Every error the Improve API returns, as JSON problem details with a stable code and a hint.
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."
}| 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
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.
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 could not be resolved. Copy it from the Implementation tab in the dashboard.
forbidden
403. The request's Origin is not in the environment's Allowed origins, or the token header is not a valid API token for the environment. See Security.
rate_limited
429. Browser (Origin) requests to the datafile are limited to 600 per minute per IP. The RateLimit-Policy header on every browser response states the limit. Wait for the Retry-After seconds, cache the datafile, or fetch it server-side with a token header, which is exempt.
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.