Errors, limits and pagination

Error envelope

Every error has the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "client_archived",
    "message": "This client is archived.",
    "param": null,
    "request_id": "req_4f9c2a1b7d3e8f60"
  }
}

type is the broad kind of error. See the table below.
code is stable. Branch on it.
message is for people. It can change, so do not parse it.
param names the field at fault, or is null.
request_id matches the X-Request-Id header. Quote it if you contact us.

`type`	Status	Meaning
`invalid_request_error`	400, 402, 404, 405, 409, 413, 415, 422	The request is not valid, or the resource is in a state that does not allow it
`authentication_error`	401	The token is missing, wrong, expired or revoked
`permission_error`	403	The token lacks a scope, the call is admin only, or the member it acts as has left
`rate_limit_error`	429	Too many requests
`api_error`	500, 502, 503	Something went wrong on our side

Status codes

Status	When
200	Success
201	Something was created
400	A field or the body is not valid
401	Authentication failed. See Authentication
402	The firm has no active subscription
403	The call is not allowed for this token
404	No such resource in this firm, or no such route
405	The method is not allowed on this path. The `Allow` header lists the ones that are
409	The resource is in a state that does not allow this, or a limit is reached
413	The body is over 256 KiB
415	The body is not JSON
422	The field asks for something Advisor never keeps, such as a tax file number
429	Rate limited
500	Something went wrong. Try again
502, 503	A service we rely on did not answer. Try again in a moment

Common codes

Request

Code	Status	Meaning
`invalid_parameter`	400	A field does not match its schema. `param` names it
`invalid_json`	400	The body is not valid JSON, or not a JSON object
`invalid_cursor`	400	`cursor` is not one we issued
`invalid_client`, `invalid_checklist`, `invalid_message`, `invalid_report`, `invalid_value`, `invalid_webhook_endpoint`	400	The input was refused. `message` says why and `param` names the field
`route_missing`	404	No route matches the path
`method_not_allowed`	405	The path exists but not for this method
`payload_too_large`	413	The body is over 256 KiB
`unsupported_media_type`	415	Send the body with `Content-Type: application/json`

Billing and plan

Code	Status	Meaning
`subscription_required`	402	The firm has no active subscription. It cannot add or invite clients or send checklists. An admin can subscribe in Settings, Billing
`client_limit_reached`	409	The plan’s 20 active clients are in use. Archive a client to add another

Permission

Code	Status	Meaning
`insufficient_scope`	403	The token lacks the scope this call needs. The message names it
`admin_required`	403	Only an admin can do this. A connected app acting as a non-admin member gets this
`member_removed`	403	The member the call acts as is no longer in the firm. For a key, that is the admin who made it
`not_message_author`	403	Only the member who wrote a message can change it

Not found

Each area has its own code, such as client_not_found, document_not_found, member_not_found, report_not_found or webhook_endpoint_not_found. All are 404. An id from another firm is treated as not found.

Conflicts

Code	Status	Meaning
`client_archived`	409	The client is archived, so this change is not allowed
`checklist_item_state`	409	The checklist item is not in a state that allows this, such as approving an item that was not submitted
`wrong_state`	409	The document is not in a state that allows this review step
`nothing_to_invite`	409	Everyone on the client with an email address has already joined
`last_admin`	409	The firm must keep at least one admin
`edit_window_closed`	409	A message can be edited for five minutes after it is posted
`connection_ended`	409	The bank connection has already ended
`value_never_kept`	422	A document type field asks for something Advisor never keeps, such as a tax file number. `param` names the field
`builtin_locked`	409	Redbark’s built-in document types, fields and facts cannot be changed. Add your own instead
`webhook_endpoint_limit`	409	The firm already has 16 webhook endpoints

Rate limits

Each API key, and each connected app, may make 120 requests a minute. The window is a fixed minute. Every successful response carries these headers:

Header	Value
`RateLimit-Limit`	The limit, 120
`RateLimit-Remaining`	Requests left in this window
`RateLimit-Reset`	Seconds until the window resets

Over the limit, the API answers 429 with code rate_limited and a Retry-After header in seconds. Wait that long, then try again.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. The limit is 120 a minute.",
    "param": null,
    "request_id": "req_9a0b1c2d3e4f5a6b"
  }
}

Retrying

Retry 429 after Retry-After.
Retry 500, 502 and 503 with a backoff.
Do not retry 400, 401, 402, 403, 404 or 409 without changing something first.
Not every write is safe to repeat. A POST that creates something can create it twice. Read before you retry a create.

Pagination

Lists return one page at a time:

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "eyJ...",
  "next_page_url": "https://advisor.redbark.com/api/v1/clients?limit=25&cursor=eyJ..."
}

limit sets the page size, from 1 to 100. The default is 25.
When has_more is true, pass next_cursor as cursor to get the next page, or call next_page_url.
Keep the other query parameters the same while you page.
When has_more is false, next_cursor and next_page_url are null.

Guides

Firm

Team

Clients

Checklists

Documents

Money

Document types

Messages

Reports

Webhooks

Webhook events

Errors, limits and pagination

Error envelope

Status codes

Common codes

Request

Billing and plan

Permission

Not found

Conflicts

Rate limits

Retrying

​Error envelope

​Status codes

​Common codes

​Request

​Billing and plan

​Permission

​Not found

​Conflicts

​Rate limits

​Retrying

​Pagination

Error envelope

Status codes

Common codes

Request

Billing and plan

Permission

Not found

Conflicts

Rate limits

Retrying

Pagination