Errors

What an error carries

• _tagstring

  Which error this is: one of those below.

• messagestring

  What went wrong, in plain language.

• hintstring

  What to do next to recover.

• retryableboolean

  True only when sending the SAME request again later can succeed (throttling, an outage). When false, change something first: see recovery.

• recoveryretry_laterrequotepick_other_slotask_customerfix_inputget_credentialsstop

  What to do next. retry_later: repeat the same call after the delay. requote: call create_quote again for the same slot. pick_other_slot: offer another opening. ask_customer: put the new facts to the human and get a fresh yes. fix_input: change the request. get_credentials: you need a different key. stop: nothing you can do; tell the user.

The errors

• InvalidRequest400

  The request is not valid: issues lists each field that is wrong.

• Unauthorized401

  The API key is missing, wrong or no longer valid.

• RateLimited429

  Too many requests: wait retryAfterMs, then repeat the same call.

• Unavailable503

  A dependency is down: wait retryAfterMs if given, then repeat the same call.

• NotFound404

  No such id, or it is not visible to this key.

• SlotUnavailable409

  The slot was taken or can no longer be booked: alternatives lists nearby openings.

• QuoteExpired410

  The quote's hold has lapsed: create a new quote.

• ConsentRequired422

  The customer's explicit consent is missing: stop and ask the human.

• InvalidState409

  The booking is not in a state that allows this.

• Forbidden403

  The key is valid but may not do this.

Examples

{
  "_tag": "InvalidRequest",
  "message": "Invalid body - customer.email: Expected an email address such as sam@example.com",
  "hint": "Fix the listed fields and retry. Field names, formats and limits are in the OpenAPI document and the tool schemas.",
  "retryable": false,
  "recovery": "fix_input",
  "issues": [
    {
      "path": "customer.email",
      "message": "Expected an email address such as sam@example.com"
    }
  ]
}

{
  "_tag": "RateLimited",
  "message": "Too many requests.",
  "hint": "Wait retryAfterMs, then repeat the same call.",
  "retryable": true,
  "recovery": "retry_later",
  "retryAfterMs": 2000
}