API reference

Errors

The JSON error shape and HTTP status codes the Homie API returns, with the error codes to handle for auth, validation and rate limits.

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

StatusCodeMeaning
400bad_requestRequired parameter missing or invalid.
401unauthorizedToken missing, malformed, expired, or revoked.
403plan_requiredThe organization doesn't have API access on its current plan.
403forbidden_scopeThe credential lacks its required read scope (api:read for API keys, mcp:read for OAuth tokens), or an organization API key was used for a user-scoped endpoint such as List connections.
404not_foundThe resource doesn't exist, or isn't in your organization's network.
429rate_limitedToo many requests. See Rate limits.
500internal_errorSomething went wrong on our side. Include the Homie-Request-Id when reporting.
503search_unavailableA network search could not finish because the network graph is temporarily overloaded. The request is fine: retry it after a short wait.

This list is the complete set of codes the API emits. A 403 distinguishes plan problems (plan_required) from permission problems (forbidden_scope).

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:

HeaderMeaning
X-RateLimit-LimitRequests allowed in the current window.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetUnix 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.

On this page