Conventions

Errors

One error shape for every endpoint, with a stable type to act on and a message for people.

The shape

Every answer with a status of 400 or above has this body:

JSON
{
  "error": {
    "type": "validation_error",
    "message": "Some fields are missing or invalid.",
    "fields": {
      "company_id": ["This company ID is taken."],
      "admin.email": ["The admin email field must be a valid email address."]
    }
  }
}
  • type is stable: write your code against it.
  • message is a sentence in English for a person. It may change; do not match on it.
  • fields comes only with validation_error: the messages per field, nested fields in dot notation (admin.email, brand.logo_light.content).

Every type

These are all the types the API answers with. The reference lists, for each endpoint, which of them it can give.

Any call

Status type Means What to do
400 invalid_json The body says it is JSON (Content-Type: application/json) and cannot be read as a JSON object Fix the body; nothing was changed
401 invalid_token The token is missing, revoked or expired, or your company's account is closed Check the Authorization header; make a new token
403 insufficient_ability The token lacks the ability the call needs; message names it Use a token with that ability
403 sandbox_only Something only a sandbox token may do: a call from Try it in the documentation, simulating a support message, or a sandbox token asking for a live token Use a sandbox token; create live tokens with a live token
404 not_found No such endpoint, or no such object for your company in the token's mode Check the ID and whether the token is live or sandbox
405 method_not_allowed The path exists, the method does not See the reference
422 validation_error Fields or query parameters are missing or invalid, or the query holds a parameter the call does not take (a typo such as ?search= is refused, never ignored); see fields Fix and send again
429 rate_limited More than 120 requests a minute per partner and mode, or over the lower limit some calls have Wait Retry-After seconds
500 server_error Something broke on Monotree's side; it is logged Retry with growing waits; tell us if it lasts
other http_error Any other refusal by the web server, with its own status code, such as 413 for a body that is too large Read message

Lists and idempotency

Status type Means What to do
400 invalid_cursor A cursor this API did not give out for this list: made by hand, changed, or taken from another list, partner or mode Start again from the first page
400 idempotency_key_required Creating a customer without an Idempotency-Key Send one
400 invalid_idempotency_key An Idempotency-Key longer than 255 characters Send a shorter one
409 idempotency_in_progress A call with the same key is still running Wait a second and retry
422 idempotency_key_reused The key was used for a different request Use a new key per request
409 idempotency_key_taken The key was used by another of your tokens. A kept answer is only given to the token that made the call Retry with the token that sent it first, or use a new key

Customers

Status type Means What to do
409 invalid_state Not possible in the customer's state: suspending a draft, retrying a live customer, insights of a customer that was never live. Also when two calls act on a customer at once and the other one won Read the customer's status, then decide
409 customer_closed Changing a cancelled or deleted customer Nothing; it cannot be changed
409 company_id_busy Another request is taking the same company ID at this moment Retry in a moment
409 external_ref_busy Another request is using the same external_ref at this moment Retry in a moment
409 limit_reached A draft too many (200 per mode), or a sandbox customer too many (500 that are not cancelled or deleted) Submit or delete drafts; cancel test customers you are done with

Sellers

Status type Means What to do
409 last_admin Disabling the only admin who can sign in, or making them a seller Make someone else an admin first
409 seller_disabled Inviting a disabled seller Enable them first
409 already_active Inviting a seller who has already chosen a password Nothing; they can sign in

Webhooks

Status type Means What to do
409 limit_reached Adding an eleventh webhook endpoint in one mode Delete one first
409 endpoints_busy Another request is adding an endpoint at this moment Retry in a moment
409 endpoint_paused Redelivering to an endpoint that is paused Switch it on with "active": true first
409 delivery_in_progress Redelivering a delivery that is being sent right now Retry in a moment

Support

Status type Means What to do
409 invalid_state The support desk refuses it as things stand; message says why. Examples: the customer wrote again since the message you named in last_seen_message, the thread is dismissed, a snooze time lies in the past, the draft is not ready or was already used, the threads to merge are from different people, the thread to escalate has no customer, or the answer to send again did not fail Read the thread again, then decide
409 nothing_to_learn Asking the assistant to learn from an answer (from_message) that holds nothing worth remembering Nothing

Retrying

Retry 429, 500, 502, 503, 504 and network errors, with growing waits (1 s, 2 s, 4 s …). Send the same Idempotency-Key on a retried POST, so it is done once.

Do not retry other 4xx answers as they are: the same request gets the same answer. Three are worth a retry after a short wait, because the cause passes by itself: 409 idempotency_in_progress, 409 company_id_busy and 409 delivery_in_progress.