Handling Errors

The v4 API uses the same HTTP status codes and error envelope as v3.

HTTP Response Codes

Code	State	Description
200	Success	Everything worked as expected
201	Created	Operation led to creation of a resource
204	No Content	Server fulfilled request, no content in response body
400	Bad Request	Request not accepted, often due to missing required parameter
401	Unauthorized	Invalid API key provided
403	Forbidden	Authenticated, but not allowed to do this — see `control_forbidden`
404	Not Found	Requested resource does not exist
409	Conflict	Resource already exists or operation conflicts with current state
415	Unsupported Media Type	`Content-Type` is missing or is not `application/json` on a request with a body
422	Unprocessable Entity	Cannot process request due to logical error
429	Too Many Requests	Rate limit exceeded. `Retry-After` says how long to wait
5xx	Server Errors	Something went wrong on Qonversion’s end (rare)

Asynchronous endpoints answer 202 Accepted — creating an export, for example, or requesting a test delivery of a scheduled report. For 5xx responses, branch on error.code (see Internal Errors), not on the status: the same internal failure can surface under different 5xx statuses.

Error Response Format

All v4 errors follow a single envelope keyed under error. There is no envelope-level meta (or _meta) key — validation field errors live inside error.details as {field, message} pairs:

{
  "error": {
    "type": "request",
    "code": "invalid_data",
    "message": "Validation failed",
    "details": [
      { "field": "short_name", "message": "Value is too long" },
      { "field": "last_name", "message": "Required" }
    ]
  }
}

error.details is omitted entirely (rather than emitted as null or []) when the failure is not field-scoped — for example, a 401 unauthorized or a 404 resource-not-found returns just {type, code, message}.

Error Types

Type	Description
`request`	Error in request validation (not enough data, invalid data, auth required)
`resource`	Request is valid but the action could not be executed
`logical`	Client can execute action but there is an error in communicating with the application
`internal`	All request handling stages succeeded but an internal error occurred

Error Codes

Request Errors

Code	Description
`invalid_data`	Validation failed. See `error.details` for the failing fields.
`invalid_request`	The request itself could not be read: a missing or wrong `Content-Type` (415), a malformed JSON body or one larger than the endpoint accepts (400), or an unrecognized URL
`control_unauthorized`	Authorization required
`control_forbidden`	Authenticated but not allowed: the project is inactive, the feature is not on your plan, or the operation needs a signed-in dashboard user, which a Secret Key alone does not provide. A wrong key returns `401` instead.
`too_many_requests`	Rate limit exceeded — back off for the number of seconds in `Retry-After` and retry
`invalid_product_id`	An entry in `product_ids` is malformed (400)
`product_not_in_project`	A product in the request does not exist in the project (400)
`idempotency_conflict`	The `Idempotency-Key` was already used with a different request body (409)

Resource Errors

Code	Description
`not_found`	Requested resource not found
`already_exists`	Requested resource already exists
`conflict`	Resource state conflicts with the requested operation

Logical Errors

Code	Status	Description
`already_completed`	422	The change has already been applied — for example, the user already has this identity
`user_already_converted`	422	The user is already linked to a different identity
`conflicting_purchases`	409	The user has purchases that conflict with another identity
`experiment_already_started` / `experiment_finished`	422	The experiment’s state does not allow this change
`cannot_delete_active_remote_configuration`	422	Archive the remote configuration first (`status: archived`), then delete it
`paid_entitlement`	422	The entitlement is backed by a paid purchase and cannot be changed this way

Internal Errors

Code	Description
`storage_error`	An internal service failed while reading or writing data
`network_error`	Internal services interaction failed
`unknown_error`	Unknown reason

Rate limits

The analytics endpoints (/v4/analytics/*) are limited to 30 requests per minute per project. Over the limit you get 429 with too_many_requests and a Retry-After header; requests sent while you are limited extend the wait.

Start here

Resource guides

REST API v4

Analytics API

Legacy: API v3

HTTP Response Codes

Error Response Format

Error Types

Error Codes

Request Errors

Resource Errors

Logical Errors

Internal Errors

Rate limits

​HTTP Response Codes

​Error Response Format

​Error Types

​Error Codes

​Request Errors

​Resource Errors

​Logical Errors

​Internal Errors

​Rate limits

HTTP Response Codes

Error Response Format

Error Types

Error Codes

Request Errors

Resource Errors

Logical Errors

Internal Errors

Rate limits