Errors

The error model#

Every error response has three parts:

• An HTTP status. It tells you the class of the error and whether a retry can help.
• A code. A stable, machine-readable string, such as revision_conflict or InsufficientScope. Branch on it.
• A message. A description for a person. It can change at any time. Do not branch on it and do not show it to buyers.

Some errors also name the fields at fault: fieldErrors in one shape, details in the other.

Error bodies do not contain internal detail. For help with a failed request, give Merxian its X-Request-Id header. See Request IDs.

Error body shapes#

The API uses two body shapes today. The error reference lists every code of each family.

{
  "errorCode": "InsufficientScope",
  "message": "This API key needs this scope: payments:refund.",
  "fieldErrors": []
}

{
  "error": {
    "code": "revision_conflict",
    "message": "The transaction changed after revision 3."
  }
}

A 404 from Retrieve a payment or Retrieve a refund has an empty body. Handle a body that is not JSON.

Read the code#

This function reads the status and the code from any error response. It is an example for Node.js 18 or later, not part of an SDK.

export interface MerxianError {
  status: number
  code: string | undefined
  message: string | undefined
  requestId: string | null
}

export async function readError(response: Response): Promise<MerxianError> {
  const text = await response.text()
  let body: any = undefined
  try {
    body = text === '' ? undefined : JSON.parse(text)
  } catch {
    body = undefined
  }
  return {
    status: response.status,
    code: body?.errorCode ?? body?.error?.code,
    message: body?.message ?? body?.error?.message,
    requestId: response.headers.get('X-Request-Id'),
  }
}

What to do by status#

Log every error with its status, its code, and its X-Request-Id. Do not log the API key or the full request headers.