Links

Error reference

Lob 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
404
401/403
Everything else

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 [email protected]

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