Lob Help Center

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

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.

Delete

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.

Delete

401/403

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

Delete

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.

Delete

HTTP status codes

200 - SUCCESS

Successful API request

401 - UNAUTHORIZED

Authorization error with your API key or account

403 - FORBIDDEN

Forbidden error with your API key or account

404 - NOT FOUND

The requested item does not exist

422 - BAD REQUEST

The query or body parameters did not pass validation

429 - TOO MANY REQUESTS

Too many requests have been sent with an API key in a given amount of time. Learn more about Lob’s rate limits here.

500 - SERVER ERROR

An internal server error occurred, please contact support@lob.com

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.


Was this article helpful?