4xx or 5xx status and the same envelope. Branch on code: it is stable, while message is for people and may change.
errors lists each failing field when the problem is tied to specific fields, as with validation_error, invalid_reference, already_exists and invalid_cursor. Treat it as optional on any error. doc_url links to the code’s section below.
All codes
Codes
validation_error
A field is missing or invalid.errors names every failing field and why.
invalid_reference
An id in the body, such aspartner_id, link_id or customer_id, doesn’t exist in your organization or doesn’t fit where you put it. errors names the field.
invalid_cursor
starting_after or ending_before isn’t a valid position in this list: the cursor is malformed, it was issued for a different sort, or the item id isn’t in the list. Pass a next_cursor or prev_cursor from a previous page. An item id is accepted as a position only with sort=created_at; with sort=updated_at it’s a validation_error.
bad_request
The request can’t be processed for another reason, such as a value out of range.message explains.
payload_too_large
The request body is over 1 MB. Split bulk work into smaller requests.unauthorized
The API key is missing, malformed or revoked. See authentication.forbidden
The key is valid but not allowed to do this.not_found
No resource with this id exists in your organization, or the route doesn’t exist.already_exists
A resource with these details exists, for example a partner with the same email in the program, a taken link value, or a customer with the same email.commission_paid
The commission is paid and locked: it can’t be approved, declined, updated or deleted. Deleting a customer with paid commissions is blocked too.commission_frozen
The commission can’t be changed.409 when it is part of a refund (a refund commission, or one on a refunded transaction). 400 when its invoice is confirmed or linked to autopayouts.
transaction_refunded
The transaction is refunded. It can’t be updated, deleted, refunded again, or have its flows rerun, and you can’t create or update a commission on it.commission_exists
The transaction already has a commission. Rerunning its flows would create a duplicate, and it can’t be deleted until the commission is removed.conflict
The action doesn’t fit the resource’s current state.message explains.
rate_limited
The key went over 25 requests per second. WaitRetry-After seconds, then retry. See rate limits.
internal_error
Something failed on Tolt’s side. Retry with backoff; for a write, check first whether it took effect. If it persists, email support@tolt.io with theRequest-Id response header.
Handle errors in code
The SDKs throw a typed error for400, 401, 404, 409 and 429, and a generic ToltApiError for anything else. The envelope is on body: