Errors
Every error is a status code and one sentence in an error field. What each code means, and what to do.
When something goes wrong, the API answers with a status code and a JSON body with one field, error, that says what happened in a sentence:
{ "error": "This key doesn't have the \"write\" scope." }The sentence is written for people, so you can show it or log it. Don't match on its exact words; they may get clearer. Use the status code.
Status codes
| Code | What happened | What to do |
|---|---|---|
400 | Something in the request is missing or not allowed, or the body isn't valid JSON | Fix the request. The message names each field, like body: Too small |
401 | No key, or the key is wrong or revoked | Check the Authorization: Bearer rk_… header |
403 | The key doesn't have the scope this needs | Make a key with that scope. See Keys and scopes |
404 | No such conversation, or one the key can't see | Check the id. Someone else's private inbox always answers 404 |
429 | More than 120 requests in a minute with this key | Wait a few seconds, then try again. See Rate limits |
500 | Something went wrong on our side | Try again shortly. If it keeps happening, write to hello@userookery.com |
Bad input
A 400 for bad input lists every problem at once, separated by semicolons, each starting with the field:
{ "error": "status: Invalid option: expected one of \"open\"|\"waiting\"|\"closed\"" }Each endpoint's fields, with their limits, are in the API reference.
Retrying
Retry a 429 or a 500, and a timeout or dropped connection, after a short wait. Before retrying a request that creates something, like a note or a reply, read Retries: a retry can make a second one.