Handling errors from the openfeed API
Every non-200 response you can expect from the openfeed Sharing API, what it means, and how your app should react.
Every openfeed API call can fail. Handling these cleanly is the difference between an integration that feels solid and one that surfaces confusing errors to your users. This is the complete list of non-200 responses you can expect and what to do about each.
Response summary
| Status | Error code | Meaning | What your app should do |
|---|---|---|---|
| 401 | Missing or expired token | Refresh the access token. If the refresh also fails, send the user back through sign-in, optionally with prompt=none. |
|
| 402 | credit_exhausted |
Application access is suspended until credits are refilled | Prompt a credit top-up in your app. Do not ask the consumer to re-consent. |
| 403 | disclosure_grant_required |
Grant is either absent or revoked by the consumer | Send the user back through sign-in, optionally with prompt=none, to establish a new grant. |
| 404 | The resource does not exist | Show a graceful “not found” state. Some endpoints (e.g. energy DER) return 404 when the consumer has no relevant asset. | |
| 429 | You are being rate-limited | Back off exponentially and show a visible loading state so the user knows the app is still working. | |
| 5xx | Transient upstream error | Retry with backoff and jitter; surface a “try again shortly” state after repeated failures. |
Handling an access revocation
If a data call returns 403 disclosure_grant_required while the user is actively using your app,
they have revoked their consent or it has otherwise ended. Treat this as a hard stop:
- Cancel any in-flight data requests.
- Include a
grant_idattribute in the PAR request, then redirect the user to reconnect. - Clean up any data you have made a commitment to the user to remove.
When it isn’t your code
Some failures are known and tracked. Before deep-debugging, check the status page — the “openfeed platform” section for defects we own, and the “data holder issues” section for problems that originate upstream at a specific bank or energy retailer (inconsistent data, unavailable APIs, partial implementations, delayed updates). Each entry lists severity, status and any workaround.