Skip to main content
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

​
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

​
string
A URI reference to the specification defining the error type. It points to the relevant section of the HTTP Semantics RFC.
​
string
A general, human-readable summary of the problem.
​
number
The HTTP status code for this occurrence of the problem.
​
string
A more specific human-readable explanation of the problem.
​
object
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:
When receiving an error, carefully examine the title, detail, and errors fields to determine the appropriate action:Example:
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.
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.
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.
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.
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.
Translate API errors into user-friendly messages in your application:
  • Use the detail field to provide specific information about what went wrong.
  • For validation errors, use the information in the errors object to highlight specific fields that need correction.
  • Avoid exposing raw error messages or stack traces to end-users.
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.
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:
  1. Authentication errors: Use invalid or expired API keys to test 401 and 403 responses.
  2. Validation errors: Send requests with missing or invalid parameters to trigger 400 responses.
  3. Rate limiting: Exceed rate limits intentionally to test your backoff and retry logic.
  4. 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:
  1. Provide the full request and error response, including all fields without your API Key.
  2. Include relevant log entries or stack traces.
  3. Describe the steps to reproduce the error.
  4. 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.
Last modified on August 9, 2024