Error reference

Lob utilizes 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. That is, 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.

401/403

These error codes should be investigated as they relate to authentication issues. No retry attempts are necessary.

Everything 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.

Note: For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.

HTTP status codes

SUCCESS	200	Successful API request
UNAUTHORIZED	401	Authorization error with your API key or account
FORBIDDEN	403	Forbidden error with your API key or account
NOT FOUND	404	The requested item does not exist
BAD REQUEST	422	The query or body parameters did not pass validation
TOO MANY REQUESTS	429	Too many requests have been sent with an API key in a given amount of time. Learn more about Lob’s rate limits here.
SERVER ERROR	500	An internal server error occurred, please contact [e-mail]

Error codes - generic

FEATURE_LIMIT_REACHED	403	The account has reached its resource limit and requires upgrading to add more.
UNRECOGNIZED_ENDPOINT	404	The requested endpoint doesn't exist.
NOT_FOUND	404	The requested resource was not found.
REQUEST_TIMEOUT	408	The request took too long. Please try again.
CONFLICT	409/422	This operation would leave data in a conflicted state.
BAD_REQUEST	422	An invalid request was made. See error message for details.
INVALID	422	An invalid request was made. See error message for details
NOT_DELETABLE	422	An attempt was made to delete a resource, but the resource cannot be deleted.
UNSUPPORTED_LOB_VERSION	422	An unsupported Lob API version was requested.
INTERNAL_SERVER_ERROR	500	An error has occurred on Lob's servers. Please try request again.
SERVICE_UNAVAILABLE	503	The Lob servers are temporarily unavailable. Please try again.

Error codes - authentication

EMAIL_REQUIRED	401	Account must have a verified email address before creating live resources.
UNAUTHORIZED	401	The request isn't authorized.
UNAUTHORIZED_TOKEN	401	Token isn't authorized.
INVALID_API_KEY	401/403	The API key is invalid.
PUBLISHABLE_KEY_NOT_ALLOWED	403	The requested operation needs a secret key, not a publishable key. See API Keys for more information.
RATE_LIMIT_EXCEEDED	429	Requests were sent too quickly and must be slowed down. Learn more about Lob’s rate limits here.

Error codes - advanced

PAYMENT_METHOD_UNVERIFIED	401	You must have a verified bank account or credit card to submit live requests.
BILLING_ADDRESS_REQUIRED	403	In order to create a live mail piece, your account needs to have a billing address.
DELETED_BANK_ACCOUNT	404	Checks cannot be created with a deleted bank account.
ADDRESS_LENGTH_EXCEEDS_LIMIT	422	The sum of to.address_line1 and to.address_line2 cannot surpass 50 characters.
BANK_ACCOUNT_ALREADY_VERIFIED	422	The bank account has already been verified.
BANK_ERROR	422	There's an issue with the bank account.
CUSTOM_ENVELOPE_INVENTORY_DEPLETED	422	Custom envelope inventory is depleted, and more will need to be ordered.
FAILED_DELIVERABILITY_STRICTNESS	422	The to address doesn't meet strictness requirements. See Account Settings to configure strictness.
FILE_PAGES_BELOW_MIN	422	Not enough pages.
FILE_PAGES_EXCEED_MAX	422	Too many pages.
FILE_SIZE_EXCEEDS_LIMIT	422	The file size is too large. See description for details.
FOREIGN_RETURN_ADDRESS	422	The from address must be a US address.
INCONSISTENT_PAGE_DIMENSIONS	422	All pages of the input file must have the same dimensions.
INVALID_BANK_ACCOUNT	422	The provided bank routing number is invalid.
INVALID_BANK_ACCOUNT_VERIFICATION	422	Verification amounts do not match.
INVALID_CHECK_INTERNATIONAL	422	Checks cannot be sent internationally.
INVALID_COUNTRY_COVID	422	The postal service in the specified country is currently unable to process the request due to COVID-19 restrictions.
INVALID_FILE	422	The file is invalid.
INVALID_FILE_DIMENSIONS	422	File dimensions are incorrect for the selected mail type.
INVALID_FILE_DOWNLOAD_TIME	422	File download from remote server took too long.
INVALID_FILE_URL	422	The file URL when creating a resource is invalid.
INVALID_IMAGE_DPI	422	DPI must be at least 300.
INVALID_INTERNATIONAL_FEATURE	422	The specified product cannot be sent to the destination.
INVALID_PERFORATION_RETURN_ENVELOPE	422	Both return_envelope and perforation must be used together.
INVALID_TEMPLATE_HTML	422	The provided HTML is invalid.
MAIL_USE_TYPE_CAN_NOT_BE_NULL	422	use_type must be one of "marketing" or "operational". Alternatively, an admin can set the account default use type in Account Settings.
MERGE_VARIABLE_REQUIRED	422	A required merge variable is missing.
MERGE_VARIABLE_WHITESPACE	422	Merge variable names cannot contain whitespace.
PDF_ENCRYPTED	422	An encrypted PDF was provided.
SPECIAL_CHARACTERS_RESTRICTED	422	Cannot use special characters for merge variable names.
UNEMBEDDED_FONTS	422	The provided PDF contains non-standard unembedded fonts. See description for details.