What do the different API response statuses and messages mean?

Below is a quick reference for common Secretary of State API response statuses, messages, and how to interpret them.

Success — 200 + Complete

Message: Business found.
‍What it means: Found a match; results were returned.‍

Message: No message
What it means: Results were returned successfully.

Processing — 202 + Incomplete

Message: [State] is taking a longer time to acquire the data. Use this retryId to check back in for your data.
What it means: The search is still in progress. Poll again using the retryId.

Bad Request — 200 + Bad request

Message: searchQuery, sosId, or searchByPersonQuery is required
‍What it means: A required search parameter is missing.

Message: searchQuery must be at least 3 characters long.
‍What it means: The business name query is too short.

Message: searchByPersonQuery must be at least 2 characters long.
‍What it means: The person search query is too short.

Message: state is a required parameter.
‍What it means: No state was provided.

Message: [State] currently not available for search. The state parameter must be camelCased, such as northCarolina, or abbreviated, such as nc.
‍What it means: The state value is invalid, unsupported, or incorrectly formatted.

Message: Usage cap exceeded. Please contact support@cobaltintelligence.com to upgrade.
‍What it means: The account has reached its usage limit.

No Results — 200 + Complete, empty results

Message: No business found in database. Try with liveData=true to search the registry in real time.
‍What it means: Nothing was found in cache. Try a live search to check the state registry directly.

Message: No business found in database. This state does not support search by person.
‍What it means: No cached result was found, and this state does not support person-based search.

Message: No business found with exact name of [query]. Did you mean one of the alternative businesses?
‍What it means: No exact match was found, but alternativeResults may include possible matches.

Partial Success — 200 + Complete with fallback

Message: We were unable to complete a live search for this business. We do have recent results, however.
‍What it means: The live search failed, but recent cached data was returned.

Message: [Error details] However, we do have recent results.
What it means: The live search had an issue, but recent cached data was available.

Message: Error happened while searching for this business. You have not been charged. However, we have found other businesses in our database that match your search.
‍What it means: The search encountered an error and was not billed, but cached alternative matches were found.

Failed — 500 + Failed

Message: An error happened. You have not been charged.
‍What it means: Something went wrong, and the lookup was not billed.‍

Message: Error happened while searching for this business. You have not been charged.
‍What it means: The search failed completely, and the lookup was not billed.

Retry Invalid — 200 + Retry Id invalid

Message: No message or expired note
What it means: The retryId does not exist, has expired, or is no longer available.

‍