Errors
Understanding and handling Posta API errors
The Posta API uses conventional HTTP response codes to indicate the success or failure of an API request. This guide will help you understand, handle, and troubleshoot the various error types you may encounter.
Quick reference
Common errors and solutions
Common errors and solutions
| Error message | Quick solution |
|---|---|
| Incorrect or expired API key | Check and update your API key |
| Too many requests | Implement exponential backoff |
| Missing required variable in template | Check template variables and ensure all required fields are provided |
| Image resolution too low | Ensure images have a DPI of at least 300 |
| Password-protected PDF | Remove password protection before uploading |
HTTP status code summary
HTTP status code summary
| Code | Description |
|---|---|
200 | OK - The request was successful |
400 | Bad Request - The request was unacceptable, often due to missing a required parameter |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found - The requested resource doesn’t exist |
409 | Conflict - The request conflicts with another request or the current state |
422 | Unprocessable Entity - The request was well-formed but had semantic errors |
429 | Too Many Requests - Rate limit exceeded |
500, 502, 503, 504 | Server Errors - An error occurred on Posta’s services |
Understanding error responses
Error response format
All API errors are returned in JSON format, conforming to the Problem Details for HTTP APIs (RFC 7807) standard. This format provides a consistent and machine-readable structure for error responses.
Error response fields
Error object
Error object
A URI reference to the specification defining the error type. It points to the relevant section of the HTTP Semantics RFC.
A general, human-readable summary of the problem.
The HTTP status code for this occurrence of the problem.
A more specific human-readable explanation of the problem.
An object containing specific validation errors. Keys are the paths to the invalid fields, and values are descriptions of the validation failures.
The errors object can provide detailed information about specific validation failures, allowing for precise error handling and user feedback.
Handling errors
Implementing robust error handling is crucial for creating reliable integrations with the Posta API. Follow these best practices to effectively manage and respond to various error scenarios:
1. Examine error responses
1. Examine error responses
When receiving an error, carefully examine the title, detail, and errors fields to determine the appropriate action:
Example:
2. Implement retry logic
2. Implement retry logic
For transient errors, implement a retry mechanism to improve the reliability of your integration:
- Retry requests for 5xx status codes (except 501 Not Implemented) and 429 Too Many Requests.
- Use exponential backoff to increase the time between retry attempts.
- Set a maximum number of retry attempts to avoid infinite loops.
3. Handle rate limiting
3. Handle rate limiting
Pay special attention to rate limit errors (status code 429):
- Implement exponential backoff with jitter to prevent synchronized retry attempts.
- Use response headers to track your rate limit status.
- Consider optimizing your code to reduce the number of API calls if you frequently hit rate limits.
Refer to our Rate limiting documentation for detailed information on handling rate limits.
4. Validate input before sending
4. Validate input before sending
To minimize validation errors (status code 400):
- Validate all required fields are present and correctly formatted before making API calls.
- Check that values meet specified constraints (e.g., string length, numeric ranges).
- Ensure all enumerated values (e.g., status codes, types) are valid.
5. Handle authentication errors
5. Handle authentication errors
For authentication errors (status codes 401 and 403):
- Verify that you’re using the correct API key.
- Check that your API key has the necessary permissions for the requested operation.
If you consistently encounter authentication errors, review your API key management practices.
6. Log errors for debugging
6. Log errors for debugging
Maintain detailed logs of all API interactions, especially errors:
- Log the full error response, including all fields returned by the API.
- Include relevant request details (endpoint, method, headers, body) in your logs.
- Use a unique identifier for each request to correlate logs with specific API calls.
7. Provide meaningful feedback to users
7. Provide meaningful feedback to users
Translate API errors into user-friendly messages in your application:
- Use the
detailfield to provide specific information about what went wrong. - For validation errors, use the information in the
errorsobject to highlight specific fields that need correction. - Avoid exposing raw error messages or stack traces to end-users.
8. Monitor and alert
8. Monitor and alert
Set up monitoring and alerting for your API integration:
- Track error rates and types to identify recurring issues.
- Set up alerts for critical errors or unusual error patterns.
- Regularly review error logs to identify areas for improvement in your integration.
Consider using application performance monitoring (APM) tools to gain insights into your API usage and error patterns.
9. Stay up-to-date
9. Stay up-to-date
Keep your integration current with the latest API changes:
- Regularly check the Changelog for updates.
- Subscribe to the Posta status page for notifications about API issues or downtime.
- Update your error handling logic if new error types or codes are introduced.
Set up a routine to review and update your integration to ensure it remains compatible with the latest API version.
By following these practices, you can create a robust error handling system that improves the reliability and user experience of your Posta API integration. Remember to test your error handling thoroughly, simulating various error scenarios to ensure your application behaves correctly in all situations.
Testing error scenarios
When developing your integration, it’s important to test various error scenarios to ensure your application handles them gracefully. Here are some strategies for simulating different errors:
- Authentication errors: Use invalid or expired API keys to test 401 and 403 responses.
- Validation errors: Send requests with missing or invalid parameters to trigger 400 responses.
- Rate limiting: Exceed rate limits intentionally to test your backoff and retry logic.
- Server errors: Use a mock server to simulate 5xx responses and test your retry mechanisms.
Always use a test environment or sandbox when simulating error scenarios to avoid impacting your production data or live mailings.
Getting help
If you encounter persistent errors or need help interpreting an error message, don’t hesitate to reach out to our support team. When contacting support:
- Provide the full request and error response, including all fields without your API Key.
- Include relevant log entries or stack traces.
- Describe the steps to reproduce the error.
- Mention any recent changes to your integration that might be related to the issue.
Contact our support team for assistance with API errors or integration issues.
By understanding and properly handling these errors, you can create a robust integration with the Posta API that gracefully manages unexpected situations and provides a seamless experience for your users.