Errors and the response envelope

The consistent error format and what each status code means.

Updated June 11, 2026

Every error returns the same JSON envelope, so you can handle failures in one place:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": ["Title can't be blank"]
  }
}

code: a stable, machine-readable string.
message: a human-readable summary.
details: present on validation errors, a list of specific problems.

Status codes

💡

Status	Code	Meaning
`400`	`bad_request`	Malformed JSON, a missing required field, or an invalid value.
`401`	`unauthorized`	Missing, malformed, or revoked API key.
`403`	`forbidden`	The key is valid but lacks the required scope.
`404`	`not_found`	The resource does not exist, or does not belong to your app.
`422`	`unprocessable_entity`	The request was understood but failed validation (see `details`).
`429`	`rate_limited`	You hit a rate limit. See Rate limits.

A note on 404

The API is strictly scoped to your app. Asking for a resource that belongs to a different app returns 404, not 403, so the API never confirms whether an id exists elsewhere.

Was this article helpful?

Introduction to the Convot API Quickstart Authentication Scopes and permissions Rate limits and quotas

Errors and the response envelope

Status codes

A note on 404

Related articles