Skip to main content

Error Responses

All Sentro API errors follow a consistent format. The HTTP status code indicates the error category, and the response body provides details.

Error Format​

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

Error Codes​

400 — Validation Error​

Returned when the request body fails validation.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name: String must contain at least 1 character(s)",
    "details": {
      "field": "name"
    }
  }
}

401 — Authentication Error​

Returned when no API key is provided, the key is invalid, expired, or revoked.

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

403 — Authorization Error​

Returned when the API key doesn't have sufficient permissions (e.g., a READ key attempting a write operation).

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "This API key does not have write access"
  }
}

404 — Not Found​

Returned when the requested resource doesn't exist or doesn't belong to your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor not found"
  }
}

409 — Conflict​

Returned when the operation conflicts with existing state.

{
  "error": {
    "code": "CONFLICT",
    "message": "A monitor with this URL already exists"
  }
}

429 — Rate Limit​

Returned when you exceed the API rate limit. See Rate Limits for details.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Rate limit exceeded. Please retry after 45 seconds.",
    "details": {
      "retryAfter": 45
    }
  }
}

402 — Plan Limit​

Returned when the operation exceeds your plan's limits (e.g., monitor count, minimum interval).

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "Monitor limit reached (25). Upgrade your plan to add more."
  }
}

500 — Internal Error​

Returned when an unexpected server error occurs. These are logged and investigated automatically.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Handling Errors​

const response = await fetch('https://api.sentro.dev/v1/monitors', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  const { error } = await response.json();

  switch (response.status) {
    case 401:
      // Re-authenticate or check API key
      break;
    case 429:
      // Wait and retry
      const retryAfter = error.details?.retryAfter || 60;
      await sleep(retryAfter * 1000);
      break;
    case 402:
      // Plan limit - notify user to upgrade
      break;
    default:
      console.error(`API error: ${error.code} - ${error.message}`);
  }
}