How to Interpret HTTP Status Code Errors from Smarty

HTTP 404 error code

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

We know you've got a status code to troubleshoot, but when you're done, come back to this section to review the docs outlined here.

Why? Because these 4 docs will help you fix errors, and more importantly, they'll prevent most of them from cropping up in the future. Most calls to our support department come from those who didn't read or apply these guidelines during implementation.

  • 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. Don't assume you know this stuff because you've been programming for years. (Yes, it'll be on the test.)
  • 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

Frustrated engineer with cables

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 a host for the embedded key used.
  • 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 are 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 turn it off. You must purchase the license or multiple licenses for the amount of lookups you need. If you dont wish to continue with the new license, you can change the renewal settings to the desired license in the subscription tab of the account.

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 is not supported by this API endpoint. Some of our APIs only allow for GET, or POST methods, while some others allow for both. In the case of our US Street API, both methods are allowed, but in cases like our US Autocomplete Pro API, we only allow for GET requests.

Status 422: Unprocessable entity

The request is constructed correctly and the parameters are correctly placed, but the submitted address or data is not able to be understood, has unfamiliar characters, or is missing crucial information to complete the request.

You can resolve this by making sure the URL is encrypted using standard URL encryption. The other way would be to ensure the address submitted is correctly entered or constructed.

Status 429: rate limit imposed

  • You are sending too many requests over too short a period of time from a single IP address. This could accidentally be triggered by stress testing the software or by having all calls routed through a single IP.
  • This can be resolved by registering the IP thats being rate-limited as a host for the embedded key used. We don't publish this value for security reasons, and keep in mind that the Autocomplete APIs (US and International) have a less strict limit than the other APIs.
  • Your plan does not allow for more lookups per second. These values are published in your account page. There is no solution for this other than to purchase a higher or faster plan from our sales team.

Status 503: Internal Server Error

Close up of organized server and network fiber cables

We're a cloud-agnostic software company. At any time, one of the servers that we will 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 building code on the user end that will momentarily 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 You should also subscribe to the email status reports from that page to get information on deprecated APIs, parameters, or other API changes.

Ready to get started?