Skip top of page navigation
AFF Web Services API Documentation API Explorer

AFF Web Services

Developer's Guide

Common Data Types

Statistical Data APIs

Geographic Area Discovery APIs

Mapping APIs


  • Submit your questions using AFF's Feedback's link.

    Request A Key

Error Handling

Types of Errors

Service methods complete successfully or complete with an error. The two types of errors reported by AFF service methods.

A business-level error is an error that indicates that some business rule or validation failed which prevented the service method from successfully processing the request. The system functioned as designed and repeating the request would produce the same error, unless the conditions that led to the validation failure changed (e.g. data/metadata was updated in AFF). An example of a business-level error is an "invalid parameter". The business-level errors map to error codes in the 400 range. Business-level errors differ from one service method to another.

A system-level error indicates that there is some problem in the AFF system that prevents it from completing the request. Repeating the request may result in successful processing of the request, provided that the root cause of the system-level error is eliminated. An example of a system-level error is "database unavailable". System-level errors map to error codes in the 500 range.

Error Response Format

An error response contains the error in the form of an error object:

error: Object {
  code: Integer,
  reason: String,
  message: String,
  locationType: ErrorLocationType,
  location: String

ErrorLocationType: Enum { path, parameter, header, body }

code : Integer

Primary error code; these error codes typically align with HTTP status codes (e.g. 400).

reason : String

Secondary error code; a standardized, high-level error description (e.g. "invalidParameter").

message : String

Detailed error description. (e.g. "Invalid Language code.").

locationType : String

An Enum that describes where in the transport layer the error occurred. One of:

  • path

  • parameter

  • header

  • body

location : String

The place in the request where the error is detected; for example: the name of a parameter.

Error Codes and Reasons

The error code and reason combinations returned by services methods are:

400 - badRequest

A required parameter is missing, the request is malformed, or the request exceeds the limit on the number of input parameters. Do not retry without fixing the problem. You need to make changes to request in order for it to work.

400 - invalidParameter

A parameter value is invalid. Do not retry without fixing the problem. You need to provide a valid value for the parameter specified in the error response.

401 - invalidAccessKey

Access Key is invalid. Do not retry without fixing the problem. You need to get a valid Access Key.

403 - insufficientPermissions

Indicates that the client does not have sufficient permissions to execute the service method. Do not retry without fixing the problem. You need to get sufficient permissions to perform the operation.

404 - resourceNotFound

Resource not found. Do not retry without fixing the problem.

429 - tooManyRequests

Indicates that the client has sent too many requests in a given amount of time ("rate limiting"). Try again later.

500 - backendError

System-level error has occurred. Do not retry this query more than once.

503 - serviceUnavailable

The server is too busy or overloaded. Try again later.

Last updated: August 02, 2017