Error handling

Every endpoint's page in the API reference lists the errors it returns, with an example of each. This page covers what they have in common: how to read an error, what to do with each kind, and how to retry safely.

Read an error

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "invalid data. see errors for more information.",
    "errors": [
      {
        "domain": "Order",
        "reason": "NotFound",
        "message": "Session 3f1c9a2e-8b4d-4e6f-9a0b-1c2d3e4f5a6b not found"
      }
    ]
  }
}

Other formats

A few errors use a different body:

To handle them all in one place, turn every error into the same shape:

// Reads any Teak error response into { status, code, message }.
async function readTeakError(res) {
  const body = await res.json().catch(() => ({}));
  const detail = Array.isArray(body.detail)
    ? body.detail.map((d) => `${d.loc?.join('.')}: ${d.msg}`).join('; ')
    : body.detail;
  const message =
    body.error?.errors?.map((e) => e.message).join('; ') ||
    detail ||
    body.msg ||
    body.non_field_errors?.join('; ') ||
    res.statusText;
  return { status: res.status, code: body.error?.code ?? res.status, message };
}

def read_teak_error(res):
    """Reads any Teak error response into (status, code, message)."""
    try:
        body = res.json()
    except ValueError:
        body = {}
    error = body.get("error") or {}
    detail = body.get("detail")
    if isinstance(detail, list):
        detail = "; ".join(f'{".".join(map(str, d.get("loc", [])))}: {d.get("msg")}' for d in detail)
    message = (
        "; ".join(e.get("message", "") for e in error.get("errors", []))
        or detail
        or body.get("msg")
        or "; ".join(body.get("non_field_errors", []))
        or res.reason
    )
    return res.status_code, error.get("code", res.status_code), message

Handle each kind of error

Decide what to do from the kind of error, not the individual message:

Retry safely

• Submit an order is safe to retry with the same session ID. The session identifies the order, so a retry can't create a second one: if an earlier attempt went through, the retry returns error.code 409, which means it's submitted. Send the same body each time. Teak keeps the first submitted order.
• Keep reference_id unique across all your orders, and reuse it only when you retry the same session. A new session with an order number that's already used is rejected.
• Retrieving an order (details or links) changes nothing, so it's always safe to retry.
• Voiding or canceling a contract twice doesn't change it twice. If a retry says the contract is already voided or canceled, the first attempt went through.
• Get a new access token for each retry, rather than reusing one that may have expired.

For Submit, the Submit an order reliably recipe puts all of this in one function, in Node.js and Python.

Keep the customer's order safe

Submit to Teak only after your own order is confirmed, and never fail or undo the customer's purchase because of a Teak error. Their payment has already gone through. Log the error, retry where the table above says to, and alert your team if it keeps failing. The checkout example submits in the background, so checkout never waits on Teak.

When you contact Teak

Send your Teak integration contact:

• The endpoint and the time of the request, with its time zone
• The environment: sandbox or production
• The HTTP status and the full response body
• The IDs involved: the session ID, your reference_id, or the policy_number

Never send your secret key or an access token.

Next steps

To see each endpoint's errors, or put this into practice:

• Look up an endpoint's errors in the API reference, for example Submit an order.
• Submit the order from your server once your own order is confirmed.