Error reference
Table of Contents
Error handling5XX codes & timeouts4XX codesHTTP status codesError codes - genericError codes - authenticationError codes - advancedLob uses response codes to indicate whether an API request has succeeded or failed.
Lob uses both Standard RESTful HTTP status codes and custom response codes, which reflect specific Lob requirements or functionality. Lob’s error response contains a message parameter containing developer-facing information about the reason for failure.
Live requests that result in a non-2XX code response are indicative of resource creation being stopped. The meaning, those requests do not incur a postage cost as no resource is created.
Error handling
Handling particular error messages can be crucial in ensuring you have a robust integration with Lob. The main categories of error status codes are 4xx and 5xx. However, timeouts can also be viewed as an error in and of itself.
5XX codes & timeouts
5XX error codes indicate a server failure, as mentioned below, whereas timeouts are indicative of just that. A request did not receive a response in the allotted amount of time. Either way, the request sent to Lob may or may not have been properly received.
To ensure that your request to Lob was successful, it is advisable to institute retry logic accordingly. When setting up this retry logic, it is essential to keep the following in mind:
Idempotency-keys will ensure your retry attempts are safe by checking that no unique mail piece is created more than once. It is crucial to use these keys to make sure you do not incur any undesired usage costs.
Backoff logic should be utilized to allow the network time to recover in the event of a short outage. Lob has sub-second response times, which means if a timeout occurs, it is likely a network issue.
3-5 retry attempts are considered best practice.
4XX codes
4XX error codes indicate something about the request was invalid. In the case of Lob, we have custom response codes that should be handled accordingly.
429
This code is related to exceeding your rate limit. If this status code is received, you should have logic in place to back off all requests to this specific endpoint and resume attempts after 5 seconds. You can utilize the 3 rate limit headers in your retry logic.
ratelimit-remaining - The number of requests remaining in the current window.
ratelimit-remaining - The number of requests remaining in the current window.
ratelimit-reset - The time at which the rate limit window resets in UTC epoch seconds.
404
If you receive a 404 response code on a GET request, it is recommended that you attempt that request with proper retry logic in place, as you may be attempting to retrieve a resource that has yet to be created. Usually, within a minute, these errors are resolved.
Delete401/403
These error codes should be investigated as they relate to authentication issues. No retry attempts are necessary.
DeleteEverything else
Other than the cases above, all errors should be acted upon as you see fit. Ultimately, the error code you receive from Lob can help you take corrective action, but not retry attempts are needed as you will get the same error message each time.
Delete