Skip to Content
Uptimeify Docs
Introduction

Error Response

Errors are returned with an appropriate HTTP status code and a JSON body containing details.

{
  "statusCode": 400,
  "statusMessage": "Invalid request body",
  "data": {
    "code": "invalidRequestBody",
    "issues": [{ "path": "url", "message": "Invalid input: expected string, received undefined" }],
    "requestId": "3f2b6c1e-8a4d-4f0e-9b7a-2c5d1e6f7a8b"
  }
}
  • data.code names the error. Branch on it, never on the text; the codes are listed in the error code list.
  • data.issues (only for invalidRequestBody) lists each rejected field with path (dot-joined) and message.
  • data.requestId identifies this one request. Quote it when you contact support.
  • statusMessage is English and says what to change: which role, token or scope is missing, or which field is wrong. It may be reworded; never parse it.
  • data.requiredScope (only for apiTokenScopeForbidden) names the scope the token lacks; data.reason (only for agentTokenReadOnly) says which agent-token rule refused the call.
  • Which role and token an endpoint needs: Permissions by endpoint.

Request ID

Every API response carries an X-Request-ID header. Send your own X-Request-ID (1 to 128 characters from A-Z, a-z, 0-9, ., _, :, -), for example your CI run, and the API echoes it back and uses it in data.requestId; otherwise it generates a UUID. A value outside that format is replaced, not rejected.

Rate limiting

To ensure service stability, the API is rate-limited.

  • Limit: 600 requests per minute per IP
  • Header: X-RateLimit-Remaining shows your remaining quota
  • Exceeded: 429 Too Many Requests

On this page