Errors

Iopole employs standard HTTP response codes to denote whether an API request has succeeded or failed.

Typically, codes in the 2xx range signify success, while codes in the 4xx range point to an error caused by the provided information (such as a missing parameter).


Codes in the 5xx range indicate server errors on Iopole end.
Certain 4xx errors, come with an error code that offers a brief explanation of the issue.

Status Code	Status	Description
20x	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid access token provided.
403	Forbidden	The access token doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on Iopole’s end.

400 - Bad request errors

404 errors indicate that the provided request is not properly formatted. All Iopole requests are validated against the appropriate JSON schema. Here is an example of a response returned for a malformed query:

{
  "statusMessage": "Request validation issues",
  "details": {
    "validation": "uuid",
    "code": "invalid_string",
    "message": "Invalid uuid",
    "path": [
      "businessEntityId"
    ]
  }
}

409 - conflict errors

409 errors indicate a conflict with the current state of the server, often due to duplicate data. All Iopole requests are processed with strict validation to prevent such conflicts.

Here is an example of a response returned for a conflicting query:

{
"code": "DUPLICATE_RESOURCE",
"statusMessage": "A resource with the same unique identifier already exists. Please ensure the provided value is unique and try again."
}