Errors

When receiving an error, carefully examine the title, detail, and errors fields to determine the appropriate action:

Example:

{
  "type": "https://datatracker.ietf.org/doc/html/rfc9110#section-15.5.1",
  "errors": {
    "recipient.individual.firstName": "firstName can not be empty"
  }
}

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.