Errors

Quo API errors name what went wrong, point at the field that caused it, and can include a trace id support uses to find your exact request.

Every error the API returns is built to help you answer three questions: what happened (title, message), where (errors[].path), and, when a trace is included, how to find this exact request again.

The envelope

Every error, regardless of status code, uses the same shape:

{
  "title": "Bad Request",
  "message": "Validation failed for 1 field.",
  "docs": "https://quo.com/docs",
  "trace": "6897907457496870895",
  "errors": [
    {
      "path": "/query/limit",
      "message": "must be <= 50",
      "value": 200,
      "schema": { "type": "integer" }
    }
  ]
}

Field	Always present	Meaning
title	Yes	The error class. Matches the HTTP status text (Bad Request, Unauthorized, and so on).
message	Yes	A human-readable summary, written for the person reading your logs rather than for end users.
docs	Yes	Where to read more. You’re here.
trace	No	A unique id for this request. See below.
errors	No	Field-level detail for validation failures. Each entry names a path, what’s wrong with it, the value you sent, and the schema it was checked against.

Handle errors by HTTP status code first and errors[].path second. The message strings are for humans and may be reworded; the structure is the contract.

Status codes

Code	When you’ll see it	Retry?
200	Success.	—
400	The request is malformed: a missing required header, an unparseable body, a parameter outside its bounds. Check errors[] for the exact field.	Not until you’ve fixed it.
401	The Authorization header is missing or doesn’t contain a valid API key.	Not until you’ve fixed it.
403	Your key is valid but this action isn’t allowed: insufficient permissions, or a workspace setting that isn’t enabled.	Not until something changes.
404	The resource doesn’t exist, or its id belongs to a different workspace than your key.	No.
422	The request is well-formed but semantically wrong. Every field parses, yet the combination can’t be processed.	Not until you’ve fixed it.
429	You’ve exceeded 10 requests per second.	Yes, with backoff.
500	Something failed on our side. If the response includes a trace id, that’s your fast path to an answer.	Yes, with backoff.

A useful asymmetry to build into your integration: 4xx errors are yours, 5xx errors are ours. Retrying a 400 in a loop won’t change the answer. It just spends your rate limit telling us the same thing.

Reading a validation error

errors[] exists so that “fix the request” never requires guesswork. Each entry is one problem:

• path points to the offending part of the request.
• message says what’s wrong with it, in one sentence.
• value echoes what you actually sent, so you can spot the gap between what your code meant and what it did.
• schema shows the constraint it was validated against.

Multiple invalid fields arrive as multiple entries in one response, so a single round trip shows everything that needs fixing.

The trace id

When an error includes a trace, log it. When you contact [e-mail] with a trace id, we can pull up the exact request: what arrived, how it was interpreted, what happened next. Without it, we’re both starting from “can you describe what you sent?”

One line of logging now saves a day of email archaeology later.

Retrying

For 429 and 5xx responses, retry with exponential backoff and jitter: first retry after about a second, doubling thereafter, with a cap on attempts that fits how time-sensitive the work is. Read requests (GET) are always safe to retry. For writes, check the endpoint’s reference page first — a retried POST can repeat its effect, so re-attempting something like a message send needs more care than re-running a read.