Errors

The Givebutter API uses standard HTTP status codes to indicate request outcomes. When errors occur, the API returns a JSON error object with details about what went wrong.

Error Response Format

All error responses follow this structure:

{
  "error": {
    "type": "error_type",
    "message": "Human-readable error description",
    "code": 400,
    "details": {
      // Optional: Additional context for validation errors
    }
  }
}

HTTP Status Codes

Success Codes (2xx)

Code	Name	Description
200	OK	Request succeeded. Response includes the requested data.
201	Created	Resource successfully created. Response includes the new resource.
204	No Content	Request succeeded, but no content to return (e.g., successful DELETE).

Client Error Codes (4xx)

Code	Name	Description	Common Causes
400	Bad Request	Malformed request syntax or invalid request parameters.	Invalid JSON, missing required parameters, malformed data
401	Unauthorized	Authentication required. API key missing, invalid, or revoked.	Missing Authorization header, invalid API key, revoked key
403	Forbidden	Authentication succeeded, but insufficient permissions for this resource.	API key lacks permissions, accessing another org’s resources
404	Not Found	Requested resource does not exist or was not found.	Invalid resource ID, resource deleted, typo in URL
405	Method Not Allowed	HTTP method not supported for this endpoint (e.g., POST on a GET-only route).	Using wrong HTTP method (POST instead of GET)
409	Conflict	Request conflicts with current resource state (e.g., duplicate record).	Duplicate resource, race condition, resource locked
422	Unprocessable Entity	Request syntax valid, but semantic errors in data (validation failures).	Missing required fields, invalid data types, values out of range
429	Too Many Requests	Rate limit exceeded. Wait before making additional requests.	Too many requests in short period, see Rate Limits

Server Error Codes (5xx)

Code	Name	Description	What To Do
500	Internal Server Error	Unexpected error on the server. Contact support if issue persists.	Retry with exponential backoff
502	Bad Gateway	Invalid response from upstream server. Usually temporary.	Retry after brief delay
503	Service Unavailable	Server temporarily unavailable (maintenance or overload).	Retry after delay, check status page
504	Gateway Timeout	Request timed out waiting for upstream server.	Retry with exponential backoff

Error Types

Each error includes a type field that categorizes the error:

Error Type	Status Code	Description	Should Retry?
authentication_error	401	Invalid or missing API key	No
permission_error	403	Valid API key but insufficient permissions	No
not_found_error	404	Requested resource doesn’t exist	No
validation_error	422	Request data failed validation	No
rate_limit_error	429	Too many requests, rate limit exceeded	Yes
conflict_error	409	Request conflicts with existing resource	Maybe
server_error	500+	Internal server error or service disruption	Yes

Validation Errors

When a request fails validation (422 status), the error response includes a details object with field-specific errors:

{
  "error": {
    "type": "validation_error",
    "message": "The given data was invalid",
    "code": 422,
    "details": {
      "email": [
        "The email field is required.",
        "The email must be a valid email address."
      ],
      "amount": [
        "The amount must be greater than 0.",
        "The amount must be a number."
      ]
    }
  }
}

Handling Errors

Check Status Codes

Always check the HTTP status code before parsing the response:

const response = await fetch('https://api.givebutter.com/v1/campaigns', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${error.error.code}: ${error.error.message}`);
  throw new Error(error.error.message);
}

const data = await response.json();

Retry Server Errors

Implement exponential backoff for 5xx errors and rate limits:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    // Retry on rate limits and server errors
    if (response.status === 429 || response.status >= 500) {
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
    }

    // Don't retry client errors
    const error = await response.json();
    throw new Error(error.error.message);
  }
}

Parse Validation Errors

Extract field-specific errors from validation responses:

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (response.status === 422) {
    const error = await response.json();
    const fieldErrors = error.error.details;

    // Display each field error to user
    Object.entries(fieldErrors).forEach(([field, messages]) => {
      console.error(`${field}: ${messages.join(', ')}`);
    });
  }
} catch (error) {
  console.error('Request failed:', error);
}

Handle Authentication Errors

Common authentication mistakes to avoid:

// ❌ Wrong - missing Bearer prefix
headers: { 'Authorization': 'YOUR_API_KEY' }

// ❌ Wrong - incorrect header name
headers: { 'X-API-Key': 'Bearer YOUR_API_KEY' }

// ✅ Correct
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }

If you get 401 errors:

Verify API key is correct (no typos or extra spaces)
Ensure you’re using the Bearer prefix
Check if key was revoked in Dashboard
Generate a new API key if needed

Debugging Tips

Check Response Status

Always inspect both the status code and response body:

curl -i "https://api.givebutter.com/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY"

Verify Request Format

Ensure your request is properly formatted: - Content-Type: application/json for POST/PUT requests

Authorization header with Bearer prefix - Valid JSON in request body - Correct endpoint URL

Test with cURL

Isolate issues by testing with cURL:

curl -X POST "https://api.givebutter.com/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Campaign","goal":10000}' \
  -v

Check API Status

Verify the API is operational: https://status.givebutter.com

Need Help?

If you’re experiencing persistent errors:

Check the API Status Page
Review the Authentication Guide
Test with cURL to isolate the issue
Contact [email protected] with:
- Error message and code
- Request details (endpoint, method, headers)
- Response body
- Timestamp of the error

Next Steps

Authentication

Learn about API authentication

Rate Limits

Understand rate limiting

Pagination

Handle paginated responses

API Overview

Back to API overview

Getting Started

Resources

Error Response Format

HTTP Status Codes

Success Codes (2xx)

Client Error Codes (4xx)

Server Error Codes (5xx)

Error Types

Validation Errors

Handling Errors

Debugging Tips

Need Help?

Next Steps

Authentication

Rate Limits

Pagination

API Overview

Getting Started

Resources

​Error Response Format

​HTTP Status Codes

​Success Codes (2xx)

​Client Error Codes (4xx)

​Server Error Codes (5xx)

​Error Types

​Validation Errors

​Handling Errors

​Debugging Tips

​Need Help?

​Next Steps

Authentication

Rate Limits

Pagination

API Overview

Error Response Format

HTTP Status Codes

Success Codes (2xx)

Client Error Codes (4xx)

Server Error Codes (5xx)

Error Types

Validation Errors

Handling Errors

Debugging Tips

Need Help?

Next Steps