Error Handling
Discover best practices for handling errors in the ParcelShield API
Overview
ParcelShield’s API uses standardized HTTP status codes to indicate request success or failure:
- 2xx: Success
- 4xx: Client-side error (invalid request or unauthorized)
- 5xx: Server-side error (ParcelShield service issue)
Every error response includes a JSON body describing the issue.
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.