Error Handling
Learn how to handle errors in the ParcelShield API
Overview
The ParcelShield API uses conventional HTTP response codes to indicate the success or failure of API requests. In general:
- Codes in the
2xxrange indicate success - Codes in the
4xxrange indicate an error that occurred due to the information provided - Codes in the
5xxrange indicate an error with ParcelShield’s servers
All error responses will include a message providing more details about the error.
Error Response Format
HTTP Status Codes
The request was successful.
The request was invalid or cannot be served. The exact error is explained in the error message.
Authentication credentials are missing or invalid.
The request is understood but it has been refused due to permissions.
The requested resource does not exist.
Too many requests hit the API too quickly. We recommend implementing exponential backoff.
Something went wrong on our end. Try again later or contact support if the problem persists.
Common Error Codes
Rate Limits
Our API implements rate limiting to ensure stability and fair usage. Rate limits are applied on a per-API key basis.
The following headers are included in all API responses:
If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how long to wait before making another request.
Best Practices
Implement Retry Logic
Implement exponential backoff when receiving rate limit errors or 5xx responses.
Handle All Status Codes
Your application should handle all possible HTTP status codes that our API might return.
Parse Error Messages
Always parse and log the error message from the response body for debugging.
Monitor Rate Limits
Keep track of rate limit headers to avoid hitting limits in production.
Need Help?
Contact Support
If you’re experiencing persistent issues or need help debugging an error, please contact our support team.