Errors and failure modes

Every failure below is presented to the user as a plain-language explanation with a recovery path. Provider error text, stack traces, tokens and authorization codes are recorded server-side and never rendered.

• The user sees what happened and what to do next, never a raw provider payload.
• Diagnostic detail is written to server logs with a correlation identifier.
• Support can locate the underlying event from that identifier without the user pasting sensitive data.
• Errors that are expected in normal use, such as a cancelled authorization, are not treated as system faults.

The user opened the Meta authorization dialog and chose not to continue. Meta returns the user to the redirect URI with an error indicating the request was denied rather than an authorization code.

• This is a normal outcome, not a defect. No token is issued and nothing is stored.
• Homa redirects to the authorization error page with a retry option.
• The single-use state cookie is cleared so a later attempt starts cleanly.

The state value on the callback does not match the value stored in the browser cookie, or the cookie is absent. The exchange is abandoned before any token request is made.

• Benign cause: the user waited long enough for the short-lived cookie to expire, or completed the flow in a different browser or private window than the one that started it.
• Benign cause: cookies are blocked, so the state was never persisted.
• Hostile cause: a cross-site request forgery attempt, where an attacker supplies their own authorization code.

Meta rejects the authorization request because the supplied redirect URI is not registered on the app, or does not match byte for byte.

• This surfaces before the user is asked to grant anything, usually as an error on the Meta dialog itself.
• It is a configuration fault rather than a user fault, so retrying without a fix will not help.
• Common causes: a trailing slash, http instead of https, an environment pointing at the wrong host, or a redirect URI registered on a different Meta app.

Authorization succeeded, but a specific permission the feature depends on was not granted. Meta allows a user to decline individual permissions while accepting others, so a partial grant is a normal result.

• The token is valid and other features continue to work.
• The dependent feature is presented as unavailable, with an explanation of which capability is missing.
• Recovery is a fresh authorization in which the user grants the outstanding permission.

A stored token has passed its expiry and Meta rejects calls made with it. Long-lived tokens still expire, so this is an expected part of the lifecycle rather than an exceptional event.

• Where the token type supports refresh, Homa attempts refresh before surfacing anything to the user.
• Where refresh is not possible, the connection is marked as needing reauthorization.
• The user is prompted to reconnect; no data is deleted as a result of expiry alone.

The user removed the integration from their Meta account settings, an administrator withdrew access to the business asset, or the asset itself was removed. The token becomes invalid without warning.

• Revocation is intentional, so Homa does not attempt to re-establish access automatically.
• The connection is marked revoked and the stored token is deleted.
• Reconnecting requires a new authorization initiated by someone with sufficient access to the asset.

Meta applies rate limits per app, per user and per asset. Exceeding a limit produces a throttling response rather than a permanent failure.

• Requests are retried with exponential backoff and jitter instead of an immediate retry loop.
• Retrying aggressively extends the throttling window and makes recovery slower.
• Webhook processing is queued, so a burst of events is absorbed rather than amplified into a burst of API calls.
• Sustained throttling is surfaced as degraded processing rather than as a hard error.

An inbound webhook request carried a missing or incorrect signature. The payload is discarded without being parsed as a domain event.

• The endpoint responds without revealing whether the signature, the timestamp or the body was at fault.
• A rejected delivery is logged as a security event, because a rising rate suggests probing.
• A sudden cluster of failures on previously working traffic usually means the app secret was rotated in one place but not the other.

Meta APIs are unavailable or degraded. Homa cannot resolve this and does not present it as a Homa fault.

• Queued work is retained and retried rather than discarded.
• The affected channel is reported as degraded, while unaffected parts of the product continue to function.
• Availability of third-party APIs is outside Homa’s control, as set out in the terms of service.

A required server-side value is absent or malformed. The most visible instance is a missing authorization URL, which disables the connect action.

• Missing configuration produces a clear message and a support route, never a crash or a blank screen.
• The message names the missing capability without printing environment variable values.
• Configuration is validated on the server, so a misconfigured deployment cannot start an authorization flow that would fail later.

When a failure persists after the recovery steps above, contact support with the approximate time, the affected channel and what you were attempting. Support can correlate that against server-side logs.