Source Link: https://help.lob.com/developer-docs/error-reference
# Error reference Lob utilizes response codes to indicate whether an API request has succeeded or failed. Lob uses both Standard RESTful [HTTP status codes](#http-status-codes-3) 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. {% hint style="info" %} 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. {% endhint %} ## 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](https://docs.lob.com/#section/Idempotent-Requests) 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. {% tabs %} {% tab title="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. {% endtab %} {% tab title="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. {% endtab %} {% tab title="401/403" %} These error codes should be investigated as they relate to authentication issues. No retry attempts are necessary. {% endtab %} {% tab title="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. {% endtab %} {% endtabs %} **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
## Error codes - generic
## Error codes - authentication
## Error codes - advanced
# Error reference Lob utilizes response codes to indicate whether an API request has succeeded or failed. Lob uses both Standard RESTful [HTTP status codes](#http-status-codes-3) 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. {% hint style="info" %} 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. {% endhint %} ## 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](https://docs.lob.com/#section/Idempotent-Requests) 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. {% tabs %} {% tab title="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. {% endtab %} {% tab title="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. {% endtab %} {% tab title="401/403" %} These error codes should be investigated as they relate to authentication issues. No retry attempts are necessary. {% endtab %} {% tab title="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. {% endtab %} {% endtabs %} **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 support@lob.com |
| 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. |
| 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. |
| 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. |