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:
{
"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."]
}
}
}typeis stable: write your code against it.messageis a sentence in English for a person. It may change; do not match on it.fieldscomes only withvalidation_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.