Error Handling

Araucaria uses conventional HTTP response codes to indicate success or failure of API requests.

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid API key / widget token
404	Not Found	Resource doesn't exist or you don't have access
409	Conflict	Invalid state transition (e.g., submitting credentials twice)
500	Internal Error	Something went wrong on our end. Contact support if it persists

All error responses include a consistent JSON structure with an error code and message.

json

              {
  "statusCode": 401,
  "code": "INVALID_API_KEY",
  "message": "Invalid or expired API key"
}
            

Code	HTTP	Description	Action
INVALID_API_KEY	401	API key is missing, malformed, or revoked	Check your API key is correct and active
INVALID_WIDGET_TOKEN	401	Widget token is expired or invalid	Create a new connection to get a fresh token
CONNECTION_NOT_FOUND	404	Connection ID doesn't exist	Verify the connection ID is correct
ACCOUNT_NOT_FOUND	404	Account ID doesn't exist	Verify the account ID is correct
INVALID_CONNECTION_STATE	409	Connection is not in the required state for this operation	Check connection status before retrying
BANK_UNAVAILABLE	503	The bank's systems are temporarily unavailable	Retry after a few minutes