General Web Service Errors

Certain, general errors will be returned in a standardized way from all API Umbrella web services. Additional, service-specific error messages may also be returned (see individual service documentation for those details). The following list describes the general errors any application may return:

Error CodeHTTP Status CodeDescription
API_KEY_MISSING403An API key was not supplied. See API key usage for details on how to pass your API key to the API.
API_KEY_INVALID403An invalid API key was supplied. Double check that the API key being passed in is valid, or signup for an API key.
API_KEY_DISABLED403The API key supplied has been disabled by an administrator. Please contact us for assistance.
API_KEY_UNAUTHORIZED403The API key supplied is not authorized to access the given service. Please contact us for assistance.
API_KEY_UNVERIFIED403The API key supplied has not been verified yet. Please check your e-mail to verify the API key. Please contact us for assistance.
HTTPS_REQUIRED400Requests to this API must be made over HTTPS. Ensure that the URL being used is over HTTPS.
OVER_RATE_LIMIT429The API key has exceeded the rate limits. See rate limits for more details or contact us for assistance.
NOT_FOUND404An API could not be found at the given URL. Check your URL.

Error Response Body

The error response body will contain an error code value from the table above and a brief description of the error. The descriptions are subject to change, so it’s suggested any error handling use the HTTP status code or the error code value for error handling (and not the content of the message description).

Error Message Response Formats

Depending on the detected format of the request, the error message response may be returned in JSON, XML, CSV, or HTML. Requests of an unknown format will return errors in JSON format.

JSON Example

  "error": {
    "code": "API_KEY_MISSING",
    "message": "No api_key was supplied. Get one at"

XML Example

    <message>No api_key was supplied. Get one at</message>

CSV Example

Error Code,Error Message
API_KEY_MISSING,No api_key was supplied. Get one at

HTML Example

    <p>No api_key was supplied. Get one at</p>