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

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

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

Whenever a rate limit is hit, the API in question will return 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 amount of time in 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 amount 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 that IP address 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 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 dynamic retry processes built in 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 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 status.smarty.com. You should also subscribe to the email status reports from that page to get information on deprecated APIs, parameters, or other API changes.