Error envelope

Every refusal on this API uses the same body, at every status:

{
  "error": {
    "code": "insufficient_scope",
    "message": "this api key requires the write_products scope"
  }
}

One shape means you write one parser and one branch, rather than one per route.

Branch on code, never on message.code is part of this contract and is safe to switch on. message is English prose for a human reading a log. Its wording can change at any time and is not part of the contract. Matching on message text produces an integration that breaks on a copy edit.

Some refusals carry an extra key

Beside code and message, a refusal may add one of three optional keys. They exist to make a failure mechanical to act on rather than to read:

Key	Appears on	What it names
`resource`	a `404`	the kind of thing that was not found, e.g. `"source"`
`field`	a `400` naming ONE offending key	that key, e.g. `"assigned_to"`
`reason`	a `400`	why the value was rejected, e.g. `"invalid_value"`, `"missing_field"`

{
  "error": {
    "code": "invalid_body",
    "field": "assigned_to",
    "reason": "missing_field",
    "message": "assigned_to is required: this is a full replace, so leaving it out would silently take the teammate who owns this conversation off it. Send the assigned_to you read back, or null to unassign"
  }
}

field appears only when ONE key is at fault. A request that omits several names them all in message and sends no field, because there is no single input for a client to point at.

Treat all three as optional. They are added where a route knows the answer, so a body carrying only code and message is not a malformed one. Branch on code first and read these for detail; field in particular lets a client point a validation message at the right input without parsing prose.

This shape covers everything

Including the responses that usually escape an API’s error format:

404 for a path that is not mounted
405 for a method the route does not accept
401 from the authentication layer, before any handler runs
429 from the rate limiter, before authentication runs
500 when something failed on our side

There is no route on /api/v1 that answers a refusal in HTML, in plain text, or in a different JSON shape. You never need a fallback parser for a body you could not decode.

Statuses

Status	Meaning	Retry?
`400`	The request was malformed or a value was invalid	No, fix the request
`401`	The credential was missing, malformed or revoked	No, fix the credential
`403`	Valid key, missing scope	No, add the scope
`404`	The record or the route does not exist	No
`405`	Wrong method for that route	No
`409`	Conflicts with current state, or an idempotency key conflict	Sometimes, see below
`413`	Body over 1 MB	No, send less
`422`	Well-formed, but rejected by a business rule	No
`429`	Rate limited	Yes, after `Retry-After`
`5xx`	Failure on our side	Yes, with backoff

Reading a 401: `code` says `unauthorized`, `reason` says what happened

In HTTP terms 401 means we do not know who you are and 403 means we do and you may not. The code on our 401 is unauthorized, which is the 403’s word. That is a compatibility decision, not an accident: renaming it would break every client already branching on it, so the accurate value is carried additively in reason.

{
  "error": {
    "code": "unauthorized",
    "reason": "credential_invalid",
    "message": "the credential could not be verified"
  }
}

`reason`	What it means	What to do
`credential_missing`	No credential was presented at all	Send the `Authorization` header
`credential_invalid`	A credential was presented and did not verify	Check the key, or mint a new one if it was rotated or revoked

The distinction is worth branching on: credential_missing is a configuration mistake you can fix in your client, while credential_invalid usually means a key was rotated or revoked and needs replacing. The message stays deliberately vague about which. It never says “this key was revoked” or “this key expired”, because that would let a probe learn which invented keys are real.

A client reading only code keeps working. reason is additive, so branching on it is optional. On a 403 the code is insufficient_scope, which already says what happened and needs no separate reason.

Every response carries a correlation id

x-request-id: 01J8Z9K2M4P6Q8R0S2T4V6W8X0

This is on every response, success or failure, including the 401 and 429 that are answered before any handler runs. It is the same value that appears in our logs for that request.

Log the x-request-id alongside your own errors. When you report a problem, quoting it is the difference between support finding the exact request in seconds and asking you a series of narrowing questions.

Handling errors

const res = await fetch(url, { headers })

if (!res.ok) {
  const { error } = await res.json()

  // branch on code, never on message
  switch (error.code) {
    case "insufficient_scope":
      throw new Error(`Add the missing scope: ${error.message}`)
    case "rate_limited":
      await sleep(Number(res.headers.get("retry-after")) * 1000)
      return retry()
    default:
      throw new Error(
        `${error.code}: ${error.message} (request ${res.headers.get("x-request-id")})`
      )
  }
}

res = requests.get(url, headers=headers)

if not res.ok:
    error = res.json()["error"]

    if error["code"] == "rate_limited":
        time.sleep(int(res.headers["retry-after"]))
        return retry()

    raise MercemurError(
        code=error["code"],
        message=error["message"],
        request_id=res.headers.get("x-request-id"),
    )

if res.StatusCode >= 400 {
    var body struct {
        Error struct {
            Code    string `json:"code"`
            Message string `json:"message"`
        } `json:"error"`
    }
    json.NewDecoder(res.Body).Decode(&body)

    return fmt.Errorf("%s: %s (request %s)",
        body.Error.Code, body.Error.Message, res.Header.Get("x-request-id"))
}

Client mistakes are never 5xx

A malformed body, a bad cursor, an unknown field or an invalid value answers 4xx. It does not answer 500. This matters for your retry logic. A 5xx from this API means something failed on our side and retrying is reasonable. If client faults could also surface as 500, you could not distinguish “retry this” from “this will fail identically forever”, and a retry loop on a permanently malformed request is just load with no chance of success.

Unknown codes

New error codes can be added as the API grows. Handle the codes you care about explicitly and fall through to a default that logs code, message and x-request-id. Do not treat an unrecognised code as success.

Get started

Integrations

Features

Essentials

Authentication

Make requests

Error handling

FAQ

Changelog

Some refusals carry an extra key

This shape covers everything

Statuses

Reading a 401: `code` says `unauthorized`, `reason` says what happened

Every response carries a correlation id

Handling errors

Client mistakes are never 5xx

Unknown codes

​Some refusals carry an extra key

​This shape covers everything

​Statuses

​Reading a 401: code says unauthorized, reason says what happened

​Every response carries a correlation id

​Handling errors

​Client mistakes are never 5xx

​Unknown codes

Some refusals carry an extra key

This shape covers everything

Statuses

Reading a 401: `code` says `unauthorized`, `reason` says what happened

Every response carries a correlation id

Handling errors

Client mistakes are never 5xx

Unknown codes