Error Handling

SplitRoute API uses standard HTTP status codes and consistent error response formats to communicate errors. This document explains how to handle errors when using the API.

Error Response Format

Error responses from the SplitRoute API follow a consistent format:

JSON
1
{
2
  "error":  "error_code",
3
  "message":  "Human-readable error message",
4
  "details":  {
5
    "field":  "Additional information about the error"
6
  }
7
}

• error: A machine-readable error code
• message: A human-readable description of the error
• details: Optional object containing additional information about the error

HTTP Status Codes

The API uses the following HTTP status codes:

Common Error Codes

Validation Errors

For validation errors (status code 422), the details field will contain information about which fields failed validation:

JSON
1
{
2
  "error":  "validation_error",
3
  "message":  "Validation failed",
4
  "details":  {
5
    "nominal_amount":  "Must be greater than 0",
6
    "destinations":  "At least one destination is required"
7
  }
8
}

Error Handling Best Practices

1. Check HTTP status codes: Always check the HTTP status code first to determine the general category of the error.

2. Parse error codes: Use the error field to programmatically handle specific error conditions.

3. Display error messages: The message field is designed to be human-readable and can be displayed to users.

4. Handle validation errors: For validation errors, check the details field to determine which fields need correction.

5. Implement retry logic: For rate limiting and temporary server errors, implement retry logic with exponential backoff.

Example: Handling Errors

Here's an example of how to handle errors in JavaScript:

JAVASCRIPT
1
async function createInvoice(invoiceData) {
2
  try {
3
    const response = await fetch('https://api.splitroute.com/api/v1/invoices', {
4
      method: 'POST',
5
      headers: {
6
        'Content-Type': 'application/json',
7
        'X-API-Key': 'your_api_key'
8
      },
9
      body: JSON.stringify(invoiceData)
10
    });
11
    
12
    const data = await response.json();
13
    
14
    if (!response.ok) {
15
      // Handle error based on status code and error code
16
      switch (response.status) {
17
        case 401:
18
          console.error('Authentication failed. Check your API key.');
19
          break;
20
        case 422:
21
          console.error('Validation failed:');
22
          if (data.details) {
23
            Object.entries(data.details).forEach(([field, error]) => {
24
              console.error(`- ${field}: ${error}`);
25
            });
26
          }
27
          break;
28
        case 429:
29
          console.error('Rate limit exceeded. Try again later.');
30
          // Implement retry logic here
31
          break;
32
        default:
33
          console.error(`Error: ${data.message}`);
34
      }
35
      throw new Error(data.message);
36
    }
37
    
38
    return data;
39
  } catch (error) {
40
    console.error('Failed to create invoice:', error);
41
    throw error;
42
  }
43
}

Webhook Error Handling

When using webhooks, it's important to handle delivery failures:

1. SplitRoute will retry failed webhook deliveries up to 5 times with exponential backoff
2. Your webhook endpoint should return a 2xx status code to acknowledge receipt
3. If all retries fail, the webhook will be marked as failed in the dashboard
4. You can manually trigger a retry for failed webhooks from the dashboard