API Troubleshooting¶

This page provides detailed explanations and solutions for common API error responses.

API Error Codes¶

This table summarizes the common error codes along with their error types and brief descriptions.

Code	Error Type	Description
`400`	#bad-request	The request is malformed or missing required parameters.
`401`	#unauthorised	Authentication is required or has failed.
`403`	#forbidden	The server understands the request but refuses to authorize it.
`404`	#not-found	The requested resource could not be located.
`429`	#too-many-requests	The rate limit has been exceeded.
`500`	#internal-server-error	An unexpected error occurred on the server.
`503`	#service-unavailable	The server is temporarily unable to handle the request.

Common Errors¶

Issue	First Steps	When to Contact Support
"403 Forbidden" error	1. Check token expiry 2. Verify permissions	If token was reset unexpectedly
Missing data	1. Check `after_version` number 2. Verify date filters	If consistent gaps persist
Slow responses	1. Reduce request frequency 2. Check network	If delays > 30 seconds regularly

Rate Limits¶

Limitations are in place to prevent overwhelming the system, these limits are:

1 request every 5 seconds - If too fast, you'll get a 429 warning
100 records per response

When limited:

Wait 5 seconds
Try again
If persistent issues, contact support@evergiving.com

Excluding Leads¶

To exclude leads from the API and prevent errors, add the condition pledges.pledge_type = 'captured'.

Error Messages¶

Bad Request¶

Explanation:
A "Bad Request" error (HTTP 400) indicates that the server could not understand the request due to invalid syntax, missing parameters, or an improperly formatted payload.

Solution:
- Validate your request syntax.
- Ensure all required parameters are included.
- Follow the API documentation for proper formatting.

Unauthorised¶

Explanation:
An "Unauthorised" error (HTTP 401) occurs when API credentials are missing, incorrect, or expired, preventing access to protected resources.

Solution:
- Verify your API key or token.
- Check that credentials are properly included in your request headers.
- Renew or update your credentials if necessary.

Forbidden¶

Explanation:
A "Forbidden" error (HTTP 403) means that the server understands your request but refuses to authorize it, often due to insufficient permissions.

Solution:
- Ensure your account has the necessary permissions.
- Confirm that the request complies with API policies.
- Contact support if you believe you should have access.

Not Found¶

Explanation:
A "Not Found" error (HTTP 404) means that the requested resource could not be located. This might result from using an incorrect endpoint or requesting a resource that doesn’t exist.

Solution:
- Verify the endpoint URL and resource identifier.
- Consult the API documentation to ensure the resource exists.

Too Many Requests¶

Explanation:
A "Too Many Requests" error (HTTP 429) indicates that you have exceeded the API’s rate limits.

Solution:
- Implement retry logic with exponential backoff.
- Reduce the frequency of your requests.
- Monitor your API usage to adjust your rate accordingly.

Internal Server Error¶

Explanation:
An "Internal Server Error" (HTTP 500) signifies an unexpected problem on the server side. This is generally not caused by your request.

Solution:
- Wait a few moments and try the request again.
- Check the API status page for any reported issues.
- Contact support if the issue persists.

Service Unavailable¶

Explanation:
A "Service Unavailable" error (HTTP 503) means that the server is temporarily unable to handle the request, often due to maintenance or overload.

Solution:
- Wait and retry the request after some time.
- Check for any maintenance notices or status updates.
- Contact support if the problem continues.