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
402	Payment Required	Billing is suspended for this client — no payment method on file
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

Billing suspension (402)

If a client's free trial ends without a payment method on file, every API request returns 402 until one is added. Scheduled syncing also stops, so account data goes stale while suspended. Existing connections and previously synced data are untouched, and access resumes as soon as a card is registered.

The response carries an action_url so you can link a user straight to the fix rather than parsing the message:

{
  "error": "BILLING_SUSPENDED",
  "message": "API access is suspended because no payment method is on file. Register a payment method at https://araucaria.money/settings to restore access immediately.",
  "action": "REGISTER_PAYMENT_METHOD",
  "action_url": "https://araucaria.money/settings"
}

Treat 402 as distinct from 401: a 401 means the API key is wrong and retrying or rotating keys is appropriate, while a 402 means the key is valid and only billing needs attention. Retrying a 402 will not clear it.

Error Response Format

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"
}
            

Error Codes

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
CONNECTION_HAS_DATA	409	Connection has synced data and cannot be deleted	Transition to DISCONNECTED instead, or use re-credential flow
CONNECTION_NOT_READY	409	Connection is not in CONNECTED state for data retrieval	Wait for connection to reach CONNECTED status
BANK_UNAVAILABLE	503	The bank's systems are temporarily unavailable	Retry after a few minutes