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	Authorization by a Secret Key required
404	Not Found	Requested resource does not exist
409	Conflict	Resource already exists or operation conflicts with current state
422	Unprocessable Entity	Cannot process request due to logical error
429	Too Many Requests	Rate limit exceeded
5xx	Server Errors	Something went wrong on Qonversion’s end (rare)

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`	Unrecognized request URL
`control_unauthorized`	Authorization required
`control_forbidden`	Authenticated but not allowed (wrong key type or scope)
`not_implemented`	Functionality at the requested address is not implemented
`rate_limited`	Too many requests — back off and retry

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	Description
`purchase_fraud`	Could not validate purchase with store, potential fraud
`relation_not_found`	Nested objects could not be found or associated

Internal Errors

Code	Description
`storage_error`	Data was not saved
`network_error`	Internal services interaction failed
`unknown_error`	Unknown reason

Authentication

Users

Overview

Get Started

Testing

Features

No-Code Builder

Remote Config

Experiments

Platform Resources

Stores Setup

SDK Migration Guides

AI-Ready

API Reference Guide

API Reference Guide v4

HTTP Response Codes

Error Response Format

Error Types

Error Codes

Request Errors

Resource Errors

Logical Errors

Internal Errors

​HTTP Response Codes

​Error Response Format

​Error Types

​Error Codes

​Request Errors

​Resource Errors

​Logical Errors

​Internal Errors

HTTP Response Codes

Error Response Format

Error Types

Error Codes

Request Errors

Resource Errors

Logical Errors

Internal Errors