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 | |
| 402 | payment_required | The workspace doesn't have an active plan |
| 402 | quota_exceeded | The workspace has used its searches or exports for now. See Rate limits |
| 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 |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. See Rate limits |
| 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.
Rate limit and quota errors already use application/problem+json, with type, title, status and detail alongside code and message. Other errors will follow. 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.