Errors, pagination and idempotency
What failed requests look like, how to page through lists and how to retry safely.
Errors
Hobson uses standard HTTP status codes. Errors from Hobson itself come back as JSON with a stable code and a readable message:
{
"code": "not_found",
"message": "Conversation not found"
}Invalid input also includes issues, which says which fields were wrong.
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_input | The request body didn't match what the endpoint expects |
| 401 | The key is missing, revoked or expired, or it's over its rate limit | |
| 402 | payment_required | The workspace doesn't have an active plan |
| 403 | forbidden | The key's role can't do this |
| 404 | not_found | It doesn't exist, or it isn't in this workspace |
| 409 | conflict | It clashes with the current state, for example something changed since you read it |
| 409 | reconnect_required | A connected account, such as Shopify or email, needs reconnecting in Hobson |
| 500 | Something went wrong on our side. We're alerted automatically | |
| 501 | not_implemented | Not available yet |
| 503 | unavailable | A service Hobson depends on is down. Try again shortly |
Treat any code you don't recognise like the status code it came with. New codes may be added.
Errors in the application/problem+json format, with a link to each error's docs, are coming soon. Coming soon
Pagination
Lists that can grow large are paged with a cursor. The response includes nextCursor. Pass it back as cursor to get the next page, and stop when nextCursor is null.
{
"tickets": [],
"nextCursor": "eyJpZCI6IjEyMyJ9"
}Treat the cursor as opaque: don't build or change one yourself. Use limit to set the page size.
Idempotency
Coming soonHobson doesn't support an Idempotency-Key header yet. Until it does, if a write request times out, check whether it happened before you retry it. Read requests are always safe to retry.
When it ships, you'll send a unique Idempotency-Key with each write. If you retry with the same key, Hobson returns the first result instead of doing the work again.