Error Handling

The Batchmates API uses conventional HTTP response codes to indicate success or failure. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

HTTP Status Codes

Name
200 OK
Description
Request succeeded
Name
201 Created
Description
Resource created successfully
Name
400 Bad Request
Description
Invalid request format or parameters
Name
401 Unauthorized
Description
Missing or invalid authentication
Name
403 Forbidden
Description
Insufficient permissions
Name
404 Not Found
Description
Resource does not exist
Name
422 Unprocessable Entity
Description
Validation errors
Name
429 Too Many Requests
Description
Rate limit exceeded
Name
500 Internal Server Error
Description
Server error occurred
Name
503 Service Unavailable
Description
Service temporarily unavailable

Error Response Format

All errors return a JSON response with the following structure:

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Specific error message"]
  }
}

Example: Validation Error

When validation fails, the response includes field-specific errors.

Response (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "amount": [
      "The amount must be at least 1."
    ]
  }
}

Common Error Scenarios

Authentication Errors

401 Unauthorized

{
  "success": false,
  "message": "Unauthenticated."
}

Solution: Include valid authentication token in Authorization header.

Permission Errors

403 Forbidden

{
  "success": false,
  "message": "Unauthorized"
}

Solution: Ensure user has required role or permissions for the operation.

Resource Not Found

404 Not Found

{
  "success": false,
  "message": "Campaign not found"
}

Solution: Verify the resource ID exists and user has access to it.

Rate Limit Exceeded

429 Too Many Requests

{
  "success": false,
  "message": "Too many requests. Please try again later."
}

Solution: Implement exponential backoff and respect rate limits.

Campaign Status Error

400 Bad Request

{
  "success": false,
  "message": "This campaign is not accepting donations"
}

Solution: Check campaign status before attempting donation.

Error Handling Best Practices

1. Check HTTP Status Code

Always check the status code before processing the response:

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}:`, error.message);
  return;
}

const data = await response.json();

2. Handle Validation Errors

Parse field-specific errors for user feedback:

if (response.status === 422) {
  const { errors } = await response.json();
  
  Object.keys(errors).forEach(field => {
    console.error(`${field}: ${errors[field].join(', ')}`);
  });
}

3. Implement Retry Logic

For rate limits and temporary failures:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

4. Log Errors

Maintain error logs for debugging:

try {
  const response = await fetch(url, options);
  const data = await response.json();
} catch (error) {
  console.error('API Error:', {
    url,
    method: options.method,
    status: error.status,
    message: error.message,
    timestamp: new Date().toISOString()
  });
}