When integrating with Ryder's Transportation & Logistics APIs, it's important to handle errors effectively and provide clear feedback to users. This guide outlines the common error codes and structures you may encounter, along with best practices for error handling.
Across all APIs, you may encounter the following HTTP status codes in the response:
`400 Bad Request`: The request was invalid or cannot be served. This usually occurs due to missing or invalid parameters.
`401 Unauthorized`: The request lacks valid authentication credentials or the provided credentials are insufficient.
`403 Forbidden`: The server understood the request but refuses to authorize it. This may happen if the user doesn't have the necessary permissions.
`404 Not Found`: The requested resource could not be found on the server.
`405 Method Not Allowed`: The request method is not supported for the requested resource.
`415 Unsupported Media Type`: The request entity has a media type that the server or resource does not support.
`429 Too Many Requests`: The user has sent too many requests in a given amount of time (rate limiting).
`500 Internal Server Error`: The server encountered an unexpected condition that prevented it from fulfilling the request.
`503 Service Unavailable`: The server is currently unable to handle the request due to a temporary overload or maintenance.
When an error occurs, the API will return a JSON response body containing an array of error objects. Each error object has the following structure:
{
"errorId": "8eaeac83-edd8-4977-880d-053b42e827e0",
"code": "XB400",
"title": "User First Name cannot be empty",
"detail": "Enter a value in the First Name field. If you do not know the first name then enter a space. The First Name field cannot be submitted with a null.",
"links": [
{
"type": "help, self",
"href": "http://developer.domain.com/dir/ref",
"description": "Link to the developer portal documentation."
}
]
}- `errorId`: A unique identifier for the specific error occurrence, useful for troubleshooting purposes.
- `code`: An application-specific error code, expressed as a string value.
- `title`: A short, human-readable summary of the error.
- `detail`: A human-readable explanation of the error, providing more details and context.
- `links`: An array of link objects that provide additional information or resources related to the error.
When consuming the Ryder Transportation & Logistics APIs, it's crucial to handle errors appropriately in your application. Here are some best practices to follow:
1. Check the HTTP status code of the response to determine the general category of the error.
2. Parse the JSON response body to extract the detailed error information.
3. Log the error details, including the `errorId`, `code`, `title`, and `detail`, for debugging and troubleshooting purposes.
4. Display user-friendly error messages to the end-user, using the `title` and `detail` fields as a reference.
5. If the error is related to user input (e.g., missing or invalid parameters), prompt the user to correct the input and resubmit the request.
6. Implement retry mechanisms for transient errors, such as `429 Too Many Requests` or `503 Service Unavailable`, with appropriate exponential backoff and maximum retry limits.
7. Utilize the `links` array to provide additional help or resources to the user, such as links to documentation or support channels.
Remember to consult the individual API documentation for any specific error codes or handling requirements. If you encounter any issues or need further assistance, please reach out to our API support team.