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

StatusCodeMeaning and fix
400invalid_emailSignup needs a valid email address.
400missing_fieldA required credential field was absent. The response names the field and lists all required ones.
401missing_keyNo bearer token. Get a free key at the signup URL in the hint.
401invalid_keyThe key is not recognised. Keys begin re_.
403early_accessYour key is valid; that platform is provisioned per account. The body carries book (a booking link) and docs. Surface the link to your human.
404not_foundUnknown route. GET / lists everything served.
404unknown_platformThat platform has no bridge. The response lists supported platforms.
409not_connectedThe platform is live but this key has no credentials for it. The hint gives the exact call to make.
429rate_limitedOver 120 requests per minute on this key. Back off and retry.
502hostaway_auth_failedThe upstream rejected the stored credentials. Re-connect the platform with fresh ones.
500internal_errorOur 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:

  1. Call the platform path you want.
  2. On 409 not_connected, read hint and ask your human for that platform's credentials, then retry.
  3. On 403 early_access, surface book to your human and continue with other work.
  4. On 429, back off and retry.