Errors
Error response shape and status codes.
All API errors return a JSON body with an error message and a code:
{
"error": "Missing or invalid bearer token",
"code": "unauthorized"
}Branch on code, not on the human-readable error text — messages may be reworded, codes won't.
Status codes
| Status | Code | Meaning |
|---|---|---|
400 | bad_request | Required parameter missing or invalid. |
401 | unauthorized | Token missing, malformed, expired, or revoked. |
403 | plan_required | The organization doesn't have API access on its current plan. |
403 | forbidden_scope | The credential is valid but the wrong kind for this endpoint — most often an organization API key calling a user-scoped endpoint like List connections or List second-degree connections. Use a user-scoped MCP token instead. |
404 | not_found | The resource doesn't exist, or isn't in your organization's network. |
429 | rate_limited | Too many requests. See Rate limits. |
500 | internal_error | Something went wrong on our side. Include the Homie-Request-Id when reporting. |
This list is the complete set of codes the API emits. A 403 distinguishes plan problems (plan_required) from credential-kind problems (forbidden_scope), so you can tell "upgrade the subscription" apart from "use a different token".
Rate limits
Rate limits are not enforced yet, and no X-RateLimit-* headers are sent today. The contract below is published in advance so clients can be written once and keep working when enforcement ships:
{
"error": "Too many requests",
"code": "rate_limited",
"retryAfterSeconds": 30
}When enforcement lands, 429 responses will carry a Retry-After header, and successful responses will carry:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix seconds when the window resets. |
Treat missing headers as "no limit currently advertised" rather than an error, and back off on 429 using retryAfterSeconds (or Retry-After) when you see one. Until then, keep automated calls reasonable.
Request IDs
Every response includes a Homie-Request-Id header. Capture it from 5xx errors so support can trace the request.