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 Code HTTP Status Code Description
API_KEY_MISSING 403 An API key was not supplied. See API key usage for details on how to pass your API key to the API.
API_KEY_INVALID 403 An invalid API key was supplied. Double check that the API key being passed in is valid, or signup for an API key.
API_KEY_DISABLED 403 The API key supplied has been disabled by an administrator. Please contact us for assistance.
API_KEY_UNAUTHORIZED 403 The API key supplied is not authorized to access the given service. Please contact us for assistance.
API_KEY_UNVERIFIED 403 The API key supplied has not been verified yet. Please check your e-mail to verify the API key. Please contact us for assistance.
HTTPS_REQUIRED 400 Requests to this API must be made over HTTPS. Ensure that the URL being used is over HTTPS.
OVER_RATE_LIMIT 429 The API key has exceeded the rate limits. See rate limits for more details or contact us for assistance.
NOT_FOUND 404 An 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 https://api.data.gov"
  }
}

XML Example

<response>
  <error>
    <code>API_KEY_MISSING</code>
    <message>No api_key was supplied. Get one at https://api.data.gov</message>
  </error>
</response>

CSV Example

Error Code,Error Message
API_KEY_MISSING,No api_key was supplied. Get one at https://api.data.gov

HTML Example

<html>
  <body>
    <h1>API_KEY_MISSING</h1>
    <p>No api_key was supplied. Get one at https://api.data.gov</p>
  </body>
</html>
Help Improve this Content