type table. The code values below are stable and safe to branch on.
Request and validation
| Code | Status | Meaning |
|---|---|---|
parameter_invalid | 400 | A field failed validation; param names it |
parameter_missing | 400 | A required field is absent; param names it |
version_required | 400 | Redbark-Version header missing |
version_invalid | 400 | The header is not YYYY-MM-DD.name, or the date predates the release |
version_unknown | 400 | The release name is not one we publish |
page_invalid | 400 | page is not a token we issued |
page_filters_changed | 400 | A filter differs from the one encoded in page |
include_invalid | 400 | An include[] value this endpoint does not offer |
idempotency_key_invalid | 400 | Idempotency-Key longer than 255 characters |
body_invalid | 400 | The request body is not valid JSON |
body_too_large | 413 | Request body over 64 KiB |
destination_incomplete | 400 | Creating a sync on a destination that has no target yet |
mapping_required | 400 | YNAB, or a Sheets per_account sync, needs account_mappings for the banking accounts |
resource_missing | 404 | No object with that id belongs to this account. Also returned when a body field references an id that does not exist (param names the field, e.g. accounts, destination, rulesets, parent) |
wrong_endpoint_for_category | 400 | The account or connection is the wrong category for this endpoint: balances and account details are banking only, transactions are banking and documents, holdings and trades are brokerage only |
invalid_date_range | 400 | from is after to |
from_too_old | 400 | from is more than about 7 years ago; banking providers serve no further back |
route_missing | 404 | No route matches the method and path |
Authentication and permission
| Code | Status | Meaning |
|---|---|---|
api_key_missing | 401 | No Authorization header |
api_key_invalid | 401 | Unknown, revoked or expired key |
insufficient_scope | 403 | The key lacks the scope the operation needs |
scope_not_held | 403 | Creating a key with a scope the caller does not hold |
ip_not_allowed | 403 | The key has an allowlist and your IP is not on it |
plan_upgrade_required | 403 | The plan has no API access |
professional_required | 403 | Brokerage data needs a Professional plan |
sync_limit_reached | 403 | The plan’s sync limit is used up |
Conflicts and idempotency
| Code | Status | Meaning |
|---|---|---|
idempotency_key_reused | 409 | Same key, different parameters |
idempotency_key_in_use | 409 | The first request with this key is still running |
key_limit_reached | 409 | Too many active API keys |
key_revoked | 409 | Rotating a revoked key |
key_already_rotated | 409 | Rotating a key that already has a replacement |
sync_already_running | 409 | A run for the sync is queued or running |
sync_disabled | 409 | Running a disabled sync |
sync_has_no_destination | 409 | The sync has no destination to run or map against |
run_not_cancellable | 409 | Only queued runs can be cancelled |
destination_in_use | 409 | Another sync already writes to this destination, or a run is writing to it during delete |
destination_disabled | 409 | The destination is auto-disabled; enable it first |
destination_exists | 409 | A webhook destination with this URL already exists |
no_resources | 409 | Webhook destinations have no resources to list |
not_a_webhook | 409 | Rotating the secret of a non-webhook destination |
provider_mismatch | 409 | Reauthorize link session provider differs from the connection’s |
category_has_children | 409 | Deleting a group that still has categories (pass cascade=true) |
category_is_group | 409 | Groups cannot claim sources or be moved under another group |
rule_limit_reached | 409 | A ruleset holds at most 20 rules |
event_destination_limit_reached | 409 | At most 10 event destinations |
no_subscribed_destination | 409 | Redelivering an event no enabled destination subscribes to |
*_create_failed, *_rotate_failed, ping_failed, categories_seed_failed, destination_link_complete_failed | 409 | A write did not take effect; safe to retry |
Rate limiting
| Code | Status | Meaning |
|---|---|---|
too_many_auth_attempts | 429 | Pre-auth bucket exhausted for this IP and key prefix |
rate_limit_exceeded | 429 | Per-key tier limit; see Retry-After |
too_many_concurrent_requests | 429 | More than 4 heavy requests in flight on one key |
Upstream and internal
| Code | Status | Meaning |
|---|---|---|
upstream_failed | 424 | The provider or destination returned a definitive error |
upstream_unavailable | 503 | The provider is down or the circuit breaker is open; retry after Retry-After |
internal_error | 500 | Our fault; quote request_id |
sync_dispatch_failed | 500 | The run row exists but could not be handed to the worker; retry the run |
connection_delete_failed | 500 | Revocation did not complete; retry |