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 400 Unauthorized Response:

{
  "type": "request_unauthenticated",
  "message": "Data required to authenticate your request is missing. Ensure that your request follows the guidelines in our documentation."
}

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_unauthenticated",
  "message": "Your request could not be authenticated. 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
    }
  ]
}

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.

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

426 - Upgrade Required

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

{
  "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. Try your request again.

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

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.

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