Docs / Errors
Errors
Every error names its cause and its fix, because an agent that cannot read the failure cannot finish the job.
Error shape
Every error is JSON with a stable error code and a human-readable message. Where there is a next action, the response carries it as a field rather than describing it in prose, so an agent can act without parsing English.
{
"error": "not_connected",
"hint": "POST /v1/connections/hostaway with accountId, clientSecret"
}
Why the errors are shaped this way. A bare 403 tells an agent nothing and it will either guess or give up. Naming the cause and the exact next call turns a failure into the next step, which is the difference between an integration that completes unattended and one that stalls waiting for a human.
Error codes
| Status | Code | Meaning and fix |
|---|---|---|
| 400 | invalid_email | Signup needs a valid email address. |
| 400 | missing_field | A required credential field was absent. The response names the field and lists all required ones. |
| 401 | missing_key | No bearer token. Get a free key at the signup URL in the hint. |
| 401 | invalid_key | The key is not recognised. Keys begin re_. |
| 403 | early_access | Your key is valid; that platform is provisioned per account. The body carries book (a booking link) and docs. Surface the link to your human. |
| 404 | not_found | Unknown route. GET / lists everything served. |
| 404 | unknown_platform | That platform has no bridge. The response lists supported platforms. |
| 409 | not_connected | The platform is live but this key has no credentials for it. The hint gives the exact call to make. |
| 429 | rate_limited | Over 120 requests per minute on this key. Back off and retry. |
| 502 | hostaway_auth_failed | The upstream rejected the stored credentials. Re-connect the platform with fresh ones. |
| 500 | internal_error | Our fault. Retry, and tell us if it persists. |
Upstream errors
When a proxied call reaches the platform and that platform returns an error, you get the platform's own status code and body unchanged, plus the x-rapideye-platform header. We do not rewrite upstream errors: a Hostaway validation error should read like a Hostaway validation error so their documentation applies.
Self-correction pattern
The intended loop for an autonomous agent:
- Call the platform path you want.
- On
409 not_connected, readhintand ask your human for that platform's credentials, then retry. - On
403 early_access, surfacebookto your human and continue with other work. - On
429, back off and retry.

