Common Error Responses

400 - Bad Request

Returns if your request was malformed or contained improper values. The response body will indicate the name of the incorrect field, its type, and the value the service received. This format is used by all services and methods under the new API.

Example Responses
Unsupported Language:

{
  "type": "invalid_input",
  "message": "An invalid request was sent in, please check the nested errors for details.",
  "errors": [
    {
      "type": "language.not_supported",
      "message": "Language is not supported. Supported languages are: [de-DE, en-US, es-ES, es-MX, fr-FR, id-ID, it-IT, ja-JP, ko-KR, pt-BR, zh-CN]",
      "fields": [
        {
          "name": "language",
          "type": "querystring",
          "value": "xx-XX"
        }
      ]
    }
  ]
}

Missing Version Value:

{
  "type": "version.required",
  "message": "You have not specified a version, the supported versions are: [1, 2]",
  "fields": [
    {
      "name": "version",
      "type": "path",
      "value": "missing"
    }
  ]
}

Invalid Version Value:

{
  "type": "version.unsupported",
  "message": "You have requested a version that is not supported, supported versions are: [1, 2]",
  "fields": [
    {
      "name": "version",
      "type": "path",
      "value": "3"
    }
  ]
}

401 - Unauthorized

Returns if your HTTP Authorization header was not found or could not be parsed. Each request to any of EPS's API services must include the unsalted SHA-512 hash of the concatenation of your API Key + shared secret + UNIX timestamp in seconds. Refer to our signature authorization page for full details.

Example 401 Unauthorized Response:

{
  "type": "request_unauthenticated",
  "message": "Data required to authenticate your request is missing. Ensure that your request follows the guidelines in our documentation.",
  "fields": [
     {
       "name": "apikey",
       "type": "header",
       "value": "jaj3982k239dka328e"
     },
     {
       "name": "signature",
       "type": "header",
       "value": "129d75332614a5bdbe0c7eb540e95a65f9d85a5b53dabb38d19b37fad6312a2bd25c12ee5a82831d55112087e1b"
     },
     {
       "name": "timestamp",
       "type": "header",
       "value": 198284729
     },
     {
       "name": "servertimestamp",
       "type": "server",
       "value": 198284729
     }
  ]
}

403 - Forbidden

Returns when your HTTP Authorization header is valid but you are not permitted to access the requested resource.

Example 403 Forbidden Response:

{
  "type": "request_unauthorized",
  "message": "Your request could not be authorized."
}

404 - Not Found

Returns if the requested API resource could not be found. Check your request URL against our documented examples.

The Geography API and Content API also use 404 responses to indicate when requested geo or content-specific files or resources cannot be located. Refer to their respective documentation pages for full examples.

Example Response:

{
    "type": "resource.not_found",
    "message": "The requested resource could not be found."
}

410 - Gone

Returns if the EPS Rapid link being followed has expired.

Example Response:

{
  "type": "link.expired",
  "message": "The link you followed has expired. Please request a new link."
}

426 - Upgrade Required

Returns if the request did not use TLS (supersedes SSL).

Example Response:

{
  "type": "upgrade_required",
  "message": "This service requires the use of TLS."
}

500 - Internal Server Error

Returns for an error within EPS's API or upstream systems. Follow the instructions in the message field if a specific action is given, otherwise, simply try your request again.

Example Responses:

{
  "type": "unknown_internal_error",
  "message": "An internal server error has occurred."
}

{
  "type": "internal_error",
  "message": "An internal server error has occurred. Please discard any previously received results in this pagination and restart the pagination from the beginning."
}

503 - Service Unavailable

Returns if there is a technical issue with the requested service. May include a Retry-After header to indicate the minimum delay (in seconds) before attempting again.

Example Response:

{
  "type": "service_unavailable",
  "message": "This service is currently unavailable."
}