Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.telluspowergroup.com/llms.txt

Use this file to discover all available pages before exploring further.

Every Tellus Open Platform API response — successful or not — follows a consistent envelope. Errors include a numeric code, a human-readable message, and (optionally) a details block with diagnostic context.

​
Error envelope

{
  "code": 1001,
  "message": "Parameter 'power' must be positive",
  "details": {
    "field": "power",
    "value": -5
  }
}
The code is the canonical machine-readable identifier. Use it for branching logic; never parse message strings — message text may change without notice.

​
Error code reference

CodeHTTPDescriptionRecommended action
0200Success—
1001400Invalid request parametersCheck parameter format and ranges
1002400Missing required parameterInspect details.field, supply the missing value
2001401Unauthenticated or invalid tokenObtain a valid token via /v1/operator/oauth/token
2002401Token expiredRefresh the token and retry the request
2003403Permission deniedVerify the client_id has the required scope (read or write)
3001404Resource not foundCheck the resource ID — it may have been deleted or be owned by a different operator
4001409Resource conflictE.g., a device with that sn is already registered
5001429Too many requestsApply backoff (see Rate Limits guide)
9001500Internal server errorRetry with backoff; if persistent, contact support

​
Retry strategy

For transient errors, an exponential-backoff retry with jitter is recommended: 
async function callWithRetry(fn: () => Promise<Response>, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fn();
    if (res.ok) return res;

    const body = await res.json().catch(() => null);
    const code = body?.code;

    // Token expired — refresh and retry once
    if (code === 2002 && attempt === 0) {
      await refreshToken();
      continue;
    }

    // Rate-limited or transient server error — backoff and retry
    if (code === 5001 || code === 9001) {
      const delay = Math.min(1000 * 2 ** attempt, 30_000);
      const jitter = Math.random() * 0.3 * delay;
      await new Promise(r => setTimeout(r, delay + jitter));
      continue;
    }

    // Anything else is a permanent error — surface to caller
    throw new ApiError(code, body?.message);
  }
  throw new Error('Max retry attempts exceeded');
}

​
Errors not to retry

The following codes indicate permanent problems with the request itself; retrying them will produce the same result. Surface them to the caller for inspection rather than retrying:
  • 1001 invalid parameters
  • 1002 missing parameter
  • 2001 invalid token (after one refresh attempt)
  • 2003 permission denied
  • 3001 resource not found
  • 4001 conflict

​
Reporting issues

If you encounter persistent 9001 errors or unexpected behaviour, please report them to support@telluspowergroup.com. Include:
  • The full request URL, method, and request body (with secrets redacted)
  • The full response including all headers
  • A timestamp range during which the issue occurred
  • Your client_id (not your client_secret)
The Tellus platform team typically responds within one business day.