Error Handling

The API uses standard HTTP status codes to indicate success or failure. Errors include a JSON body with details.

Status codes

Code	Meaning
200	Success
400	Bad Request — invalid parameters
401	Unauthorized — invalid or missing API key
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Error response format

All errors return a consistent JSON structure:

json

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required.",
    "details": {}
  }
}

Handling errors in code

python

import requests

response = requests.get("https://api.poyst.com/api/health")

if response.status_code == 200:
    data = response.json()
else:
    error = response.json().get("error", {})
    print(f"Error {response.status_code}: {error.get('message')}")