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.

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

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

Essentials

Authentication

Make requests

Error handling

This shape covers everything

Statuses

Every response carries a correlation id

Handling errors

Client mistakes are never 5xx

Unknown codes

​This shape covers everything

​Statuses

​Every response carries a correlation id

​Handling errors

​Client mistakes are never 5xx

​Unknown codes

This shape covers everything

Statuses

Every response carries a correlation id

Handling errors

Client mistakes are never 5xx

Unknown codes