Errors

Every error except 411 and 413 is application/problem+json (RFC 9457) with the extra fields errorCode and requestId, and on some errors errors or requiredPermission. A 503 can come without requestId.

404

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "The resource does not exist.",
  "errorCode": "RESOURCE_NOT_FOUND",
  "requestId": "3f1c9a52-7b0e-4d2a-9c61-5e8f2b7d4a10"
}

Field	Type	Description
type	string	Always about:blank.
title	string	The HTTP status phrase, for example Not Found.
status	integer	The HTTP status code.
detail	string	What went wrong. The text can change; branch on errorCode. A validation error names the invalid fields, never the values sent.
errorCode	string	The stable error code.
requestId	string	The ID of the request, also sent as the X-Request-Id header on every response. Include it when contacting support.
errors	array	Only on a 400 that names fields: one entry per invalid field or query parameter. See Invalid fields.
requiredPermission	object	Only on a 403 with FORBIDDEN. See A missing permission.

Status	errorCode	When
400	MALFORMED_REQUEST	The body is not JSON of the shape of the operation, or a query parameter has the wrong type. See Request bodies.
400	VALIDATION_FAILED	A field or a parameter breaks a rule of the request. errors names each field; the operation page lists the rules.
401	UNAUTHORIZED	The token is missing, malformed, unknown or expired, or its API key is disabled or deleted. The response has the header WWW-Authenticate: Bearer.
403	FORBIDDEN	The API key does not hold the API permission the operation needs. See A missing permission.
403	IP_ADDRESS_NOT_ON_ACCESS_LIST	The request comes from an address that is not on the IP access list of the API key, or the list is empty while an IP access list is required. The detail names the address. See IP access list.
403	CLIENT_ADDRESS_UNKNOWN	The address the request comes from cannot be determined.
404	RESOURCE_NOT_FOUND	The path does not exist, or the resource does not exist or the API key has no access to it: another Organization, or a context of another Organization or of another Service.
405	METHOD_NOT_ALLOWED	The path exists, but not with this method. The Allow header lists the methods it has.
406	NOT_ACCEPTABLE	The Accept header does not allow application/json.
409	ALREADY_EXISTS	The resource or the value already exists: a name another access policy has, a device that already has an active whitelisting. The detail says what to do instead.
409	PRECONDITION_FAILED	The current state of the resource does not allow the change, and the refusal has no code of its own. The detail says what to do instead.
415	UNSUPPORTED_MEDIA_TYPE	The request body is not application/json.
429	RATE_LIMITED	Too many requests. See When a limit is exceeded.
500	INTERNAL	An unexpected error.
503	SERVICE_UNAVAILABLE	A service the API depends on did not answer, so the API key could not be checked. Nothing was done. The Retry-After header gives the number of seconds to wait before the next request.

A 400 is a request that can be corrected by changing it. A refusal that depends on existing data is a 409. New error codes can be added within v2. Handle an unknown errorCode by its HTTP status.

Domain codes

The codes in the table are the generic codes: they mean the same on every operation. A refusal by a rule of a Service has a domain code: a 409 whose code starts with the name of the Service, SIGN_IN_ for Sign In. Each operation page lists the domain codes of the operation. The OpenAPI document lists them per operation as x-error-codes, and as x-reason-codes for the codes that appear only as the reason of an item in a batch result. An item of a batch result that was not done as asked carries reason with an errorCode from the same set and a detail.

Sign In

Code	Status	Operations	Meaning
SIGN_IN_FALLBACK_POLICY_NOT_DELETABLE	409	Delete an access policy	The policy is the fallback policy of the context, which cannot be deleted.
SIGN_IN_CONFERENCE_LIMITS_INVALID	409	Create an access policy, Update an access policy	manageConferences is true, and the conference visitor limits of the policy are not valid. Correct them in the Admin Dashboard.
SIGN_IN_WHITELISTING_ENDED	409	Update a whitelisting	The whitelisting has ended, by its end date or by a revocation. Create a new whitelisting for the device.
SIGN_IN_WHITELISTING_REFUSED	409, or 200 in reason	Create a whitelisting; the reason of a REJECTED item in Create whitelistings in a batch	The rules for whitelistings of the context refuse the device.
SIGN_IN_EMAIL_PATTERN_IN_OTHER_POLICY	200 in reason	The reason of an IN_OTHER_POLICY item in Add email patterns	Another access policy of the context has the pattern.

Request bodies

A request body is read strictly. Each case returns 400 with MALFORMED_REQUEST and one entry in errors that names the field:

Request	errors[].code
A value of another JSON type than the field’s: a number for a string, a string for a boolean, [] for a string, "" for a list	INVALID_TYPE
A date that is not YYYY-MM-DD, also ""	INVALID_FORMAT
A field the operation does not have	UNKNOWN_FIELD
A key sent twice	DUPLICATE

A body that is not JSON, or has content after the JSON value, returns 400 with MALFORMED_REQUEST and no errors. A body that is not application/json, for example YAML, returns 415. An Accept header that does not allow application/json returns 406 with NOT_ACCEPTABLE before anything is done; without an Accept header the response is JSON.

In a request body, null means the same as leaving the field out. null on a required field returns 400 with VALIDATION_FAILED and an entry in errors for the field with the code REQUIRED.

Invalid fields

A 400 that names fields lists them in errors, one entry per invalid field or query parameter:

400

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "limit: Must be 1 to 100.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "4c9d1e72-3b5a-4f08-9d26-7e1a0c3b5f84",
  "errors": [
    { "field": "limit", "code": "OUT_OF_RANGE", "detail": "Must be 1 to 100." }
  ]
}

Field	Type	Description
errors[].field	string	A path in the request body, for example whitelistings[3].mac, or the name of a query parameter, for example limit.
errors[].code	string	Why it is invalid: REQUIRED, INVALID_TYPE, INVALID_FORMAT, OUT_OF_RANGE, INVALID_VALUE, UNKNOWN_FIELD or DUPLICATE. New codes can be added within v2.
errors[].detail	string	What to change. The text can change; branch on code.

A missing permission

A 403 with FORBIDDEN because the API key lacks a permission names the permission in detail and in requiredPermission:

403

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "The API key needs Read access to Organization. An administrator can grant it in the API key's permissions.",
  "errorCode": "FORBIDDEN",
  "requestId": "7a3e0c52-1d4b-4e8f-9b26-3c5f8a1d7e04",
  "requiredPermission": { "permission": "organizations", "level": "READ" }
}

Field	Type	Description
requiredPermission.permission	string	The ID of the API permission, for example organizations. Each resource overview under Core Resources names the ID of its permission. New IDs can be added within v2.
requiredPermission.level	string	READ or WRITE. Write includes Read.

When a limit is exceeded

A request that exceeds a limit returns 429 with the errorCode RATE_LIMITED and a Retry-After header: the number of seconds to wait before the next request. The request was not processed.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 45

429

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after the time given in Retry-After.",
  "errorCode": "RATE_LIMITED",
  "requestId": "8b2d4e61-0c3f-4a97-b5e2-19d7c6f0a384"
}