Errors

Handle Roots API errors by using the documented HTTP status and error message, then confirm the production error contract before automating retries.

See API availability before using error behavior in production.

Error envelope

The currently documented error response uses this JSON shape:

{
  "error": "Invalid credentials"
}

Treat the error string as diagnostic information for a human or application log. Do not build business logic that depends on the exact wording of an error message.

Documented HTTP statuses

Status	Documented use	Your action
`400 Bad Request`	Invalid request, such as an invalid payment source/destination pair or an invalid association.	Correct the request data. Do not retry unchanged.
`401 Unauthorized`	Invalid login credentials or no authenticated session where required.	Check the credentials or authentication state. Do not retry unchanged.
`403 Forbidden`	The caller lacks permission for an operation, such as API-key creation.	Request the required role or permission. Do not retry unchanged.
`404 Not Found`	A referenced resource is not found for selected endpoints.	Verify the identifier and owning company context.
`409 Conflict`	A duplicate association exists.	Retrieve the existing record or resolve the duplicate condition.

Handle errors safely

Record the HTTP status, endpoint, internal correlation ID, and sanitized error response.
Do not log passwords, API-key secrets, full account numbers, or sensitive document content.
Correct client-side validation errors before resubmitting a request.
Route authorization failures to the owner of the relevant access control.
Reconcile uncertain payment outcomes before you create another payment instruction.

Target schema — confirm in API reference

The production error contract is not yet published. Confirm the following before implementing generalized error handling:

Full HTTP-status coverage and error codes.
A stable machine-readable error identifier.
Request or correlation IDs.
Rate-limit responses and retry-after behavior.
Validation-error field paths.
Retry-safe outcomes for network failures and timeouts.

Next steps

Read Idempotency before designing payment retries.
Read Create payments for invalid payment instructions.
Read Security and data handling for safe logging practices.