Responses and errors · playit API docs

Response format#

Every response is a JSON object with two fields: status and data.

SuccessJSON

{"status": "success", "data": null}

`status`	HTTP code	Meaning
`success`	`200`	The request completed. `data` contains the result.
`fail`	`400`	The request did not complete. `data` tells you why.
`error`	`400`, `401`, `500`	The request was not valid, not authorized, or failed on the server.

Always check the HTTP code and the status field.

Failures#

A fail response means that the API understood the request but could not complete it. For example, the firewall does not exist.

FailureJSON

{"status": "fail", "data": "FirewallNotFound"}

Each endpoint has its own failure values. The endpoint pages list them.

Authentication errors#

If the API key is not valid, the API returns HTTP 401:

Authentication errorJSON

{
  "status": "error",
  "data": {
    "type": "auth",
    "message": "ScopeNotAllowed"
  }
}

`message`	Meaning
`AuthRequired`	The request has no API key.
`InvalidApiKey`	The key does not exist or is no longer active.
`ScopeNotAllowed`	The key does not have the scope for this endpoint.
`NotAllowedWithReadOnly`	The key is read-only, and this endpoint changes data.

Validation errors#

If the request body is not valid JSON, or a field has the wrong type, the API returns HTTP 400. data.type is validation, and data.message tells you what is wrong.

Server errors#

If the request fails on the server, the API returns HTTP 500:

Server errorJSON

{
  "status": "error",
  "data": {
    "type": "internal",
    "message": {"trace_id": "example-trace-id"}
  }
}

If you contact support, include the trace_id.