API — Error Codes & Response Format

HTTP Status Codes

Common API error conditions
Code	Status	Description	Solution
400	Bad Request	Expected body or field type is incorrect.	Check the JSON body and field names.
401	Unauthorized	Token is missing, invalid or revoked.	Check the Bearer token header and token lifetime.
402	Payment Required	The endpoint requiring premium was called on the free plan.	Use a paid plan or appropriate capability.
403	Forbidden	Site scope or capability check failed.	Try again with the correct site ID and the correct token.
404	Not Found	Site not found or the requested data has not yet been created.	Verify the Site ID and that the corresponding resource has been produced.
422	Unprocessable Entity	Laravel validation error.	Read missing/incorrect fields from the validation errors object.
429	Too Many Requests	Throttle limit exceeded.	Wait until Retry-After and try again.
500	Server Error	Unexpected server error.	Log the request and escalate it to support if it recurs.

Error Response Structure

The API does not use a single fixed error envelope. Auth errors return an error field; Laravel validation errors come with message and errors object. errors object shows which field is invalid and why - see the full response to speed up debugging.

{
  "error": "Invalid or revoked token"
}

{
  "message": "The active field is required.",
  "errors": {
    "active": [
      "The active field is required."
    ]
  }
}

429 and Retry Strategy

429 The Retry-After banner returns with the response Too Many Requests. Do not repeat the same request before this time expires.

Use linear backoff for short bursts and exponential backoff for repeated failures. Do not resend the same failed request at frequent intervals, especially in polling integrations.