Documentation
Feedback
Guides
API Reference

Guides
API usage
Error handling and best practices
Handling errors and exceptions
Handling errors and exceptions

Learn how to handle errors and exceptions in VTEX API Core Commerce APIs to build resilient applications.

Handling errors and exceptions is essential for building resilient applications that can effectively navigate temporary restrictions from VTEX Core Commerce API's rate limits. Exception handling and error recovery mechanisms help your store respond gracefully to rate limit exceeded errors without impacting user interactions. They also minimize unnecessary retries and resource wastage by introducing appropriate wait times and contributing to responsible resource management.

To implement effective error handling in rate-limiting scenarios, consider the VTEX API response status codes article and prioritize the best practices outlined in this article, with a specific emphasis on the code families of 3xx (Redirection), 4xx (Client Errors), and 5xx (Server Errors).

Handle 3xx errors

HTTP status codes in the 3xx range are used for redirection purposes, usually demanding the user agent to take additional actions to fulfill the request.

Error codeError handling strategies
308 Permanent Redirect
  • Update the URL or endpoint used in the request to the new provided location.
  • Ensure the redirection is valid and current at the time of the request.
  • Confirm if the redirection is genuinely permanent rather than temporary.
  • Update your bookmarks, links, or references to reflect the new resource location.

Handle 4xx errors

HTTP status codes in the 4xx range denote client errors, typically originating from issues on the client side.

Error codeError handling strategies
400 Bad Request
  • Refer to API Reference for the expected request format.
  • Review the request parameters.
  • Validate the request structure and syntax.
  • Ensure all required parameters are included.
401 Unauthorized
  • Verify the authentication method used. Refer to Authentication for more information.
  • Ensure that authentication tokens or API keys are correctly passed in the request headers.
  • Re-authenticate with valid credentials.
403 Forbidden
  • Ensure you have the appropriate roles to perform the desired action.
  • Check the expiration or validity of your access credentials.
404 Not Found
  • Refer to API Reference for correct endpoint naming.
  • Double-check the URL or endpoint for accuracy.
  • Confirm if the resource has been moved or deleted.
  • Check the VTEX status page for real-time outages and incident reports. If the issue persists, reach out to VTEX Support.
405 Method Not Allowed
  • Ensure the request method matches the allowed methods for the resource. Refer to VTEX API Reference for supported methods.
  • Check for spelling errors in the method used.
429 Too Many Requests
  • Reduce the frequency of requests by optimizing code to limit unnecessary API calls or batch requests when possible.
  • Implement an exponential backoff strategy to gradually increase the delay between retries after receiving a 429 error.
  • Monitor your API request patterns closely to identify any areas that may be triggering rate limits frequently and adjust accordingly.
  • Consider implementing a queue system to better manage and distribute requests over time.
  • In case of persistent rate limit issues, consider reaching out to VTEX Support for further assistance or clarification.

Handle 5xx errors

HTTP status codes in the 5xx range indicate server errors, revealing issues on the server side that hinder request fulfillment. Effective error handling in this category is essential for maintaining a reliable application.

Error codeError handling strategies
500 Internal Server Error
  • Check if the issue is on your end or the server's.
  • If possible, test the same request on different tools to confirm the issue.
  • Check the VTEX status page for real-time outages and incident reports.
  • Retry the request after some time, as the error might be temporary.
  • If the issue persists, reach out to VTEX Support.
503 Service Unavailable
  • Retry the request after some time, as the error might be temporary.
  • Check the VTEX status page for real-time outages and incident reports.
  • If the issue persists, reach out to VTEX Support.
504 Gateway Timeout
Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest Edits (GitHub)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page