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

​

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

​

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:

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.

​

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.

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.