Error Codes

Q: How do I find the correct site ID?

Use the GET /api/v1/sites endpoint to list all your sites. Each site object includes an id field you can use in other API calls.

AttractOS API returns structured JSON errors with a code, message, and HTTP status. Use the code field for programmatic error handling and the error message for debugging. All errors follow the format: {"error": "message", "code": "ERROR_CODE"}.

Error Response Format

All API errors return a JSON object with these fields:

Error Response Structure

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "retry_after": 30  // Only for rate limit errors
}

Authentication Errors (401)

These errors occur when your API key is missing, invalid, or revoked.

MISSING_KEY 401

No Authorization header was provided in the request.

Fix: Add the Authorization header with your API key: Authorization: Bearer YOUR_API_KEY

INVALID_KEY 401

The API key provided is invalid or has been revoked.

Fix: Check that your API key is correct. Generate a new key from your dashboard if needed.

USER_NOT_FOUND 401

The user associated with this API key no longer exists.

Fix: This typically means the account was deleted. Create a new account and API key.

Authorization Errors (403)

These errors occur when you're authenticated but lack permission for the resource.

SITE_NOT_FOUND 403

The site ID does not exist or you do not have access to it.

Fix: Verify the site ID is correct. Use GET /api/v1/sites to list your accessible sites.

PLAN_REQUIRED 403

This feature requires a higher plan tier.

Fix: Upgrade to Pro to access this feature (e.g., hourly granularity timeseries).

Request Errors (400)

These errors occur when your request is malformed or missing required parameters.

MISSING_SITE_ID 400

The siteId path parameter is required but was not provided.

Fix: Include the site ID in the URL path: /api/v1/sites/{siteId}/stats

INVALID_DATE_RANGE 400

The start or end date parameter is invalid.

Fix: Use ISO 8601 date format: YYYY-MM-DD (e.g., 2024-01-15)

INVALID_JSON 400

The request body contains invalid JSON.

Fix: Check your JSON syntax. Use a JSON validator if needed.

Rate Limit Errors (429)

These errors occur when you've exceeded your request or event limits.

RATE_LIMITED 429

You have exceeded the API rate limit for your plan.

Fix: Wait for the time specified in retry_after. Consider upgrading for higher limits.

LIMIT_EXCEEDED 429

You have exceeded your monthly event tracking quota.

Fix: Wait until the next billing cycle or upgrade your plan for more events.

Server Errors (500)

These errors indicate an unexpected problem on our end.

SERVER_ERROR 500

An unexpected error occurred on the server.

Fix: Retry the request. If the error persists, contact [email protected].

Frequently Asked Questions

Why am I getting INVALID_KEY when my key worked before?

Your API key may have been revoked (manually or due to suspicious activity). Check your dashboard Settings > API Keys to see if the key is still active. Generate a new key if needed.

How do I find the correct site ID?

Use the GET /api/v1/sites endpoint to list all your sites. Each site object includes an id field you can use in other API calls.

What should I do if I keep getting SERVER_ERROR?

First, check the status page for any ongoing incidents. If the service is operational, try the request again with exponential backoff. If the error persists, contact support with the request details.