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

Error messageQuick solution
Incorrect or expired API keyCheck and update your API key
Too many requestsImplement exponential backoff
Missing required variable in templateCheck template variables and ensure all required fields are provided
Image resolution too lowEnsure images have a DPI of at least 300
Password-protected PDFRemove password protection before uploading
CodeDescription
200OK - The request was successful
400Bad Request - The request was unacceptable, often due to missing a required parameter
401Unauthorized
403Forbidden
404Not Found - The requested resource doesn’t exist
409Conflict - The request conflicts with another request or the current state
422Unprocessable Entity - The request was well-formed but had semantic errors
429Too Many Requests - Rate limit exceeded
500, 502, 503, 504Server 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. 
{
    "type": "https://datatracker.ietf.org/doc/html/rfc9110#section-15.5.1",
    "title": "An error occurred while processing your request",
    "status": 400,
    "detail": "Validation failed",
    "errors": {
        "recipient.individual.firstName": "firstName can not be empty"
    }
}

​
Error response fields

​
type
string
A URI reference to the specification defining the error type. It points to the relevant section of the HTTP Semantics RFC.
​
title
string
A general, human-readable summary of the problem.
​
status
number
The HTTP status code for this occurrence of the problem.
​
detail
string
A more specific human-readable explanation of the problem.
​
errors
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:
{
  "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.
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.