API basics
Errors
One error shape for the Texa API, what each status means, and which ones to retry.
Every error from the Texa API has the same shape, and the request's id is in the X-Request-Id
header. Quote it to Texa support and we can find the request at once.
{"error": {"type": "invalid_request_error", "code": "invalid",
"message": "a message has text", "field": "text"}}
| Field | Meaning |
|---|---|
type |
the family of error, below |
code |
a stable machine-readable reason, such as invalid, not_found, conversation_closed, rate_limited, insufficient_credits |
message |
a sentence for a developer. Don't show it to customers |
field |
for a request that isn't valid, the part that's wrong |
Statuses
| Status | Meaning | Retry? |
|---|---|---|
| 400, 422 | The request is not valid. field names the part |
No: fix the request |
| 401 | The key is missing, unknown or revoked | No |
| 402 | Your prepaid credits are used up. Top up in Texa Desk under Texa AI → Credits and billing | After topping up |
| 403 | The key can't do this: a sandbox route with a live key, a suspended account | No |
| 404 | No such route, or nothing with that id in your account | No |
| 409 | The conversation's state doesn't allow it (closed, or with a person), or an Idempotency-Key was reused with a different body |
No: read code |
| 429 | Too many requests. Wait Retry-After seconds |
Yes, after the wait |
| 500, 502, 503 | Our side | Yes, with the same Idempotency-Key or message_id |
Codes worth handling
code |
When | What to do |
|---|---|---|
conversation_closed |
You sent a message to a closed conversation | Open a new conversation for the customer and send it there (example) |
rate_limited |
Over your requests per minute | Wait Retry-After seconds |
idempotency_key_reused |
The same Idempotency-Key with a different body |
Use a new key for a new request |
idempotency_in_progress |
A retry arrived while the first request with that key is still running | Wait a moment and retry |
invalid_api_key |
The key is missing, unknown or revoked | Check the key, or make a new one |
insufficient_credits |
The prepaid balance is used up | Top up in Texa Desk |
test_key_required |
A sandbox route (fixtures) with a live key | Use a texa_test_… key |
account_suspended |
The account is suspended | Talk to Texa support |
too_large |
An upload over the size limit | Send a smaller file |
not_found |
Nothing with that id in this account and environment | Check you're using the right key: sandbox and live don't share conversations |
New codes may be added. Treat an unknown code by its status.
Texa Desk API errors
The Texa Desk API answers in its own shape: {"error": "..."} or {"message": "...", "errors": [...]},
with 401 for a missing or wrong api_access_token, 404 for something outside the person's
account or view, and 422 for a refused change, with a sentence you can show as it is.
Failures Texa AI meets
An error in your systems (an action that fails or times out) is not an API error. Texa AI tells the customer honestly that it couldn't check and offers a person, and the action's result is in the events. See actions.