Error Handling Guide

This guide provides an overview of how the Shipping Channels API handles errors and how you can effectively interpret and respond to them in your applications.

Standard Error Response Structure

When an error occurs, the API will return a JSON response with a consistent structure, typically including an error object with a message and, for validation errors, an errors object containing specific field-level messages.

{
  "error": {
    "message": "A descriptive error message.",
    "errors": {
      "field_name": [
        "Specific error message for field_name."
      ]
    }
  }
}

Common HTTP Status Codes

The API uses standard HTTP status codes to indicate the type of response. Here are some of the most common ones you'll encounter:

Status Code	Description	Common Causes
200 OK	The request was successful.	Successful GET, PUT, PATCH, DELETE operations.
201 Created	The request was successful and a new resource was created.	Successful POST operations.
204 No Content	The request was successful, but there is no content to return.	Successful DELETE operations.
400 Bad Request	The request was malformed or invalid.	Missing required parameters, invalid data format.
401 Unauthorized	Authentication failed or was not provided.	Missing or invalid API key.
403 Forbidden	The authenticated user does not have permission to access the resource.	Attempting to access another user's data.
404 Not Found	The requested resource could not be found.	Invalid ID for a resource.
405 Method Not Allowed	The HTTP method used is not supported for the requested resource.	Using GET on an endpoint that only accepts POST.
422 Unprocessable Entity	The request was well-formed but could not be processed due to semantic errors.	Validation errors (e.g., invalid email format, non-existent shipping channel ID).
429 Too Many Requests	You have sent too many requests in a given amount of time.	Exceeding rate limits.
500 Internal Server Error	An unexpected error occurred on the server.	Server-side issues. If this persists, please contact support.

Handling Validation Errors (422 Unprocessable Entity)

Validation errors are the most common type of error you'll encounter when sending data to the API. When a 422 Unprocessable Entity status code is returned, the errors object in the response will provide detailed information about which fields failed validation and why.

Example Validation Error Response:

{
  "error": {
    "message": "The given data was invalid.",
    "errors": {
      "shipping_channel_id": [
        "The selected shipping channel is invalid."
      ],
      "parcel.weight_amount": [
        "The parcel.weight_amount must be at least 0.01."
      ]
    }
  }
}

Your application should parse this errors object and display appropriate messages to the user, guiding them to correct their input.

Rate Limiting (429 Too Many Requests)

To ensure fair usage and stability of the API, rate limits are enforced. If you exceed the allowed number of requests within a certain timeframe, you will receive a 429 Too Many Requests response.

When a rate limit is hit, the API will include the following headers in the response to help you manage your request rate:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed in the current period.
X-RateLimit-Remaining	The number of requests remaining in the current period.
X-RateLimit-Reset	The time (in UTC epoch seconds) at which the current period will end.

It is recommended to implement a retry mechanism with exponential backoff when encountering 429 responses to avoid continuously hitting the rate limit.

Debugging Tips

• Check Request Body/Parameters: Double-check that your request body and query parameters match the API documentation exactly, including data types and required fields.
• Verify Authentication: Ensure your API key is correct and included in the Authorization header as Bearer YOUR_API_KEY.
• Inspect Response Headers: For rate limiting issues, examine the X-RateLimit-* headers.
• Log Errors: Implement robust error logging in your application to capture full error responses, which can be invaluable for debugging.
• Contact Support: If you encounter persistent 500 Internal Server Error responses or other unexpected behavior, please provide your request details and any error messages to our support team for assistance.