API Responses

The API uses HTTP status codes to indicate whether a request has succeeded or failed. 2xx status codes represent a successful request, 4xx/5xx status codes represent a failed request. If you receive an error HTTP status code, check the body for an error code and message.

HTTP Response Codes

Status Code	Description	Most Likely Cause
2xx	Successful Request
400	Bad Request	Invalid/missing data
401	Unauthorized	Invalid/missing credentials
403	Forbidden	Insufficient permissions to perform the operation on the resource
404	Not Found	The resource does not exist, e.g. invalid/non-existent iGUIDE id
409	Conflict	Attempt to overwrite a resource, e.g. when creating a user with an email that already exists
429	Too Many Requests	Exceeded the API rate limit
500	Server-side error	Something is wrong on the server side, retry later. If the error persists, please report it.
501	Not Implemented	The operation is not implemented.

API Response Object

When an operation fails (HTTP status code >=400), the body of the HTTP reply will contain a more detailed explanation of the failure. The body is a JSON object with the following scheme:

Property	Type	Description
code	string	The error code
message	string	A developer-facing status message. Ideally this should not be displayed to an end user.

Examples

Response for successful operation

HTTP/1.1 200 OK
Content-Type: application/json

{
  ... SOME JSON DATA HERE ...
}

Error response for invalid request body

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": "invalid_argument",
  "message": "Invalid request body"
}

Error response for unauthorized request

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": "unauthenticated",
  "message": "Unauthorized request"
}