How to interpret HTTP status code errors from Smarty

Welcome to our little space to help you understand Smarty's HTTP status errors, what they mean, and how to prevent them in the future.

Now, here's a rundown of the most common errors you might see when calling our APIs:

• Preventing future errors: HTTP status and otherwise
• 400 status: Bad request
• 401 status: Authentication required
• 402 status: Payment required
• 404 status: Not found
• 405 status: Method not allowed
• 422 status: Unprocessable entity
• 429 status: Rate limit imposed
• 503 status: Internal server error

Preventing future errors: HTTP status and otherwise

We know you’re here to troubleshoot a status code. Once you’ve resolved it, we recommend coming back to review the four docs in this section.

They’ll help you understand how to address common errors and, more importantly, how to avoid many of them during implementation. These guidelines cover several of the issues our support team sees most often, so applying them early can save you time on troubleshooting later.

• Best practices: This is the most important page of our documentation. It'll help you with error handling, network hiccups, maximum uptime, security compliance, and SLAs, and provide many good practices to make your integration with Smarty run predictably.
• Technical requirements: This page describes the technical requirements for using our services. 
• Authentication: Here, well describe how to authenticate with various Smarty APIs. All requests must be authenticated.
• Licensing: This page describes how to indicate which license to use when communicating with the various Smarty APIs.

Status 400: Bad request

This request isn't constructed correctly and needs to be rewritten or reviewed. This could also be due to URL encryption, as well. Please review your code and inspect the request itself. Print it to your terminal in a server-side request or inspect the network tab in a browser request.

Status 401: Unauthorized/authentication required

These errors may arise when calling our APIs from a cloud server, using a VPN or VDI, or testing from a cloud environment. Other common reasons include:

• You have entered the keys incorrectly. Please double-check the key values.
• You may have the incorrect or no referer registered as the host for the embedded key.
• You may be calling or sending an HTTP request from a cloud environment using the embedded key, which isn't allowed for security reasons.

This can be resolved by registering the server's IP as a host for the key as well. Usually, these are dynamic, so we recommend creating a proxy server.

Status 402: Payment required error

• You don't have the license to call this API, or you’re using a parameter that isn't allowed in the API call. (i.e., Enhanced match is included in US Core, but NOT US Legacy Standard.)
• You have renewed your license 4 times in a 24-hour period, and the automatic renewal has been turned off. This is to prevent runaway code, and there's no way to disable it. You must purchase a license, or multiple licenses, for the number of lookups you need. If you don't wish to continue with the new license, you can change the renewal settings to the desired license in the account's subscription tab.

Status 404: Not found

The URL you called doesn't exist. Please check the URL endpoint and make sure it's spelled correctly.

405 status: Method not allowed

This request method isn’t supported by this API endpoint. Some of our APIs only allow GET or POST, while others allow both. For our US Street API, both methods are allowed, but for our US Autocomplete API, we only allow GET requests.

Status 422: Unprocessable entity

The request is constructed correctly, and the parameters are in the correct order, but the submitted address or data can’t be understood, contains unfamiliar characters, or is missing crucial information to complete the request.

You can resolve this by ensuring the URL is encrypted with standard URL encoding. The other way would be to ensure that the submitted address is correctly entered or constructed.

Status 429: Rate limit imposed

Whenever a rate limit is hit, the API returns a 429 HTTP status code, indicating that the IP or license in use is being throttled. Along with this status code, a “Retry-After” header will be returned, indicating the number of seconds until the rate limit expires.

We recommend using the “Retry-After” header to implement a “dynamic retry process.”

Whenever a 429 status code is returned, we recommend capturing the “Retry-After” header and waiting the indicated number of seconds before retrying the request or sending any other requests. This retry process will increase the efficiency of recovering from a rate limit and prevent further throttling.

If you’re regularly experiencing 429 status codes on a single IP address while using an embedded key, you may be hitting a “security-based rate limit.” If the IP in question is known and trusted, you may want to whitelist it on the embedded key in use.

If you’re regularly experiencing a 429 status code and it’s not a “security-based rate limit,” your plan might not allow for more address lookups per second. Your allotted values are published on your account page. One solution is to purchase a higher or faster plan from our sales team.

All that said, the easiest way to handle rate limits is to use one of our SDKs! They have built-in dynamic retry processes to efficiently handle 429 status codes.

For more information about rate limits, check out our Best practices page!

Status 503: Internal server error

We're a cloud-agnostic software company. At any time, one of the servers that we’ll be using may be experiencing issues.

These errors are typically intermittent, especially so in our case. This is usually because of a rotation of IPs or servers that may be slow or unresponsive. This is out of our control, and we recommend adding user-side build code to temporarily blacklist any IPs that may be causing this issue.

We usually resolve these issues pretty quickly and will publish any major problems on our status page at status.smarty.com. You should also subscribe to the email status reports on that page to receive information about deprecated APIs, parameters, and other API changes.