Handle errors and retries

Responses and errors describes what a failure looks like, and Retries when repeating a call is safe. This guide applies both to three situations every integration meets: a booking that timed out, a version conflict on an update, and a 429. Read those two pages first; this one doesn’t repeat them. The examples use curl and jq, with an API key in ARBOL_API_KEY, and every id and patient detail in them is an example.

Keep what each answer says

Each decision below rests on the status, error.code, error.retryable and, when present, the Retry-After header. Keep the headers and the body of each answer apart, and log metadata.requestId with every failure:

status=$(curl --silent --show-error --max-time 30 \
  --dump-header headers.txt --output body.json --write-out "%{http_code}" \
  https://api.getarbol.com/v1/agenda/booking-requirements \
  --header "Authorization: Bearer $ARBOL_API_KEY")
jq --arg status "$status" '{$status, code: .error.code, retryable: .error.retryable, requestId: .metadata.requestId}' body.json

When no answer arrives at all, curl exits with an error, such as 28 when --max-time runs out, and the status is 000. For a write, that’s an outcome you don’t know yet.

A booking that timed out

You sent agenda.bookings.create and got no answer, a 504 UPSTREAM_TIMEOUT or a 502 OUTCOME_UNKNOWN. Whatever retryable says, the appointment may exist, and the booking operations take no idempotency key. Find out before you do anything else:

The other booking writes need the same care, each according to its Effect:

A version conflict on an update

An update that takes expectedVersion applies only if nobody changed the record since you read it. Here a sync job sets a Raíz contact’s summary with raiz.contacts.update, which needs raiz:contacts:write, sending the version that raiz.contacts.get answered:

curl https://api.getarbol.com/v1/raiz/contacts/cnt_00000000-0000-4000-8000-000000000009 \
  --request PATCH \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "expectedVersion": 7,
    "summary": "Prefers to be contacted in the morning."
  }'

Someone changed the contact in between, so it answers 409 with this error:

{
  "code": "VERSION_CONFLICT",
  "message": "The resource changed after it was read. Read it again and retry with the new version.",
  "retryable": false,
  "data": {}
}

retryable is false: the same request would fail the same way. Instead:

Agenda’s updates that take a version, of services, offerings, resources, schedule rules and appointments, accept only people, so they come from staff tools. They answer 409 with a code that names the record, and you handle each the same way:

A 429

429 RATE_LIMITED is retryable: wait the seconds in Retry-After, then send the same request again. The limit counts the requests of one credential, which is one more reason to give each system its own key. Wrap your calls so every flow waits the same way; in TypeScript, arbol is the client from createClient, as in the TypeScript SDK:

# Sends one request; while the answer is 429, waits Retry-After seconds and sends it again.
arbol_request() {
  local attempt status delay
  for attempt in 1 2 3 4 5; do
    status=$(curl --silent --show-error --max-time 30 \
      --dump-header headers.txt --output body.json --write-out "%{http_code}" \
      --header "Authorization: Bearer $ARBOL_API_KEY" "$@") || return 1
    [ "$status" = 429 ] || break
    delay=$(awk 'tolower($1) == "retry-after:" { print $2 + 0 }' headers.txt)
    sleep "${delay:-$((2 ** attempt))}"
  done
  cat body.json
}

arbol_request --get https://api.getarbol.com/v1/agenda/nearest-booking-slots \
  --data-urlencode "serviceId=svc_00000000-0000-4000-8000-000000000001" \
  --data-urlencode "timezone=America/Bogota"

import { ApiError } from "@arbol-ai/sdk";

// Calls the API; while the answer is 429, waits Retry-After seconds and calls again.
async function withRetryAfter<T>(call: () => Promise<T>, attempts = 5): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await call();
    } catch (error) {
      if (!(error instanceof ApiError) || error.status !== 429 || attempt === attempts) throw error;
      const seconds = Number(error.response.headers.get("retry-after")) || 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    }
  }
}

const { data } = await withRetryAfter(() =>
  arbol.agenda.nearestBookingSlots.list({ serviceId: "svc_00000000-0000-4000-8000-000000000001", timezone: "America/Bogota" }),
);

Both stop after five attempts and give up at once when no answer arrives: for a write, that’s the unknown outcome above, and waiting doesn’t resolve it. Repeat a 503 or 504 the same way only for reads, with exponential backoff and jitter; a write that ended in either goes through the steps of a booking that timed out.