Error Handling

This guide covers how to handle errors when working with the TreasuryPath API, including common error scenarios and best practices for error recovery.

Error Response Format

All TreasuryPath API errors follow a consistent JSON format using the standardized error structure:

{
  "errors": [
    {
      "field": "amount_cents",
      "message": "must be greater than 0"
    }
  ]
}

Error Response Fields:

errors: Array of error objects
field: The field or context related to the error. For non-field-specific errors (such as rate limiting or general request errors), this value will be base
message: Human-readable error description

HTTP Status Codes

The TreasuryPath API uses standard HTTP status codes to indicate success or failure:

2xx Success

200 OK - Request succeeded
201 Created - Resource created successfully
204 No Content - Request succeeded, no content returned

4xx Client Errors

400 Bad Request - Invalid request format or parameters
401 Unauthorized - Authentication required or invalid credentials
403 Forbidden - Authenticated but insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists or conflicting state
422 Unprocessable Entity - Valid format but semantic errors
429 Too Many Requests - Rate limit exceeded

5xx Server Errors

500 Internal Server Error - Unexpected server error
502 Bad Gateway - Upstream service error
503 Service Unavailable - Service temporarily unavailable
504 Gateway Timeout - Upstream service timeout

Common Error Scenarios

Authentication Errors

401 Unauthorized - Invalid or Expired Token

{
  "errors": [
    {
      "field": "api_key",
      "message": "Invalid or revoked API credentials"
    }
  ]
}

Solution: Request a new JWT token using your API credentials via the /api/v1/sessions endpoint. See the Authentication Guide for details on token refresh strategies.

Validation Errors

422 Unprocessable Entity - Field Validation

{
  "errors": [
    {
      "field": "amount_cents",
      "message": "must be greater than 0"
    },
    {
      "field": "currency",
      "message": "is required"
    }
  ]
}

Solution: Check the errors array for specific field errors and correct your request. Each error object indicates the problematic field and describes what needs to be fixed.

Resource Errors

404 Not Found - Resource Missing

{
  "errors": [
    {
      "field": "id",
      "message": "Resource not found"
    }
  ]
}

Solution: Verify the resource ID is correct and ensure you have access to it. Check that you're using the correct resource IDs in the request path.

Rate Limiting

429 Too Many Requests

{
  "errors": [
    {
      "field": "base",
      "message": "Rate limit exceeded. Please try again later."
    }
  ]
}

Solution: Implement exponential backoff when receiving 429 responses. Wait before retrying your request. See the API Basics - Rate Limiting section for recommended approaches.

Error Handling Best Practices

1. Always Check HTTP Status Codes

Check the HTTP status code before parsing the response body. This helps you quickly identify whether the request succeeded or failed, and what type of error occurred.

2xx codes: Request succeeded - parse and process the response data
4xx codes: Client error - check the errors array for details and fix your request
5xx codes: Server error - implement retry logic with exponential backoff

2. Implement Retry Logic

When to Retry:

429 (Rate Limit): Always retry with exponential backoff
5xx (Server Errors): Retry with exponential backoff
4xx (Client Errors): Do not retry - these indicate problems with your request that need to be fixed

Retry Strategy:

Use exponential backoff to avoid overwhelming the API
Set a maximum number of retry attempts (typically 3-5)
Log each retry attempt for debugging

3. Handle Validation Errors Gracefully

When you receive a 422 response:

Parse the errors array from the response body
Extract the field and message for each error
Present clear error messages to your users
Correct the request based on the field-specific error messages

4. Parse Error Responses Correctly

All errors follow the standardized format with an errors array. Each error object contains:

field: The parameter or context that caused the error
message: A human-readable description of what went wrong

Always parse this structure to provide meaningful feedback.

5. Log Errors Securely

What NOT to Log:

API secrets or JWT tokens
Sensitive user data
Full request bodies containing credentials

Ensure your error logging excludes sensitive information to maintain security and comply with data protection requirements.

6. Handle Token Expiration

JWT tokens expire after 24 hours. When you receive a 401 error:

Check if it's due to token expiration
Request a new token via /api/v1/sessions
Retry the original request with the new token
Consider implementing proactive token refresh to avoid interruptions

See the Authentication Guide for token refresh strategies.

Webhook Error Handling

When receiving webhooks from TreasuryPath:

Verify Signatures: Always verify webhook signatures before processing
Return 200 Quickly: Acknowledge receipt with a 200 status code within a few seconds
Process Asynchronously: Handle webhook processing in the background
Handle Failures: If processing fails, return an appropriate error code so TreasuryPath can retry
Log Webhook Events: Track webhook delivery and processing for debugging

Monitoring and Alerting

Set up monitoring for:

High error rates - Alert when error rate exceeds threshold
Authentication failures - Monitor for token expiration issues
Rate limiting - Track when you're hitting rate limits
Webhook failures - Monitor webhook delivery success rates

Next Steps

API Basics - Learn about HTTP status codes and standard response formats
Authentication - Understand authentication errors and token refresh strategies
Webhooks - Set up webhook error handling and retry logic
FAQ - Find answers to frequently asked questions