All Trackpilots API errors follow a consistent response structure:
{
"success": false,
"statusCode": 401,
"statusMessage": "Upgrade required",
"data": null,
"error": {
"message": "Upgrade required to use Trackpilots APIs",
"code": "PLAN_EXPIRED"
}
}
| Field | Type | Description |
|---|
success | boolean | Always false for error responses |
statusCode | number | HTTP-equivalent status code |
statusMessage | string | Short human-readable status label |
data | null | Always null for error responses |
error.message | string | Detailed description of the error |
error.code | string | Machine-readable error code for programmatic handling |
Authentication & Authorization Errors
All Trackpilots API endpoints require a valid API key sent in the Authorization header. The following errors are returned when authentication fails.
The request was sent without an Authorization header.
{
"success": false,
"statusCode": 401,
"statusMessage": "Authentication token header is missing",
"data": null,
"error": {
"message": "Authorization header is missing",
"code": "AUTHORIZATION_HEADER_MISSING"
}
}
Authorization header to every request.
Authorization: Bearer YOUR_API_KEY
INVALID_API_KEY_SCHEMA
The Authorization header was present but did not use the Bearer scheme.
{
"success": false,
"statusCode": 401,
"statusMessage": "Invalid authentication token schema",
"data": null,
"error": {
"message": "Authorization header must start with 'Bearer'",
"code": "INVALID_API_KEY_SCHEMA"
}
}
Bearer (note the space).
Authorization: Bearer YOUR_API_KEY
Token YOUR_API_KEY, API_KEY, or the key value directly without a scheme.
API_KEY_MISSING
The Authorization: Bearer header was present but the key value after it was empty.
{
"success": false,
"statusCode": 401,
"statusMessage": "Authentication token is missing",
"data": null,
"error": {
"message": "API key value is missing",
"code": "API_KEY_MISSING"
}
}
undefined at the time the request is made. Check environment variable loading if using .env files.
INVALID_API_KEY
The API key was provided but does not match any active key on record — either it was never valid, has been deleted, or has been deactivated.
{
"success": false,
"statusCode": 401,
"statusMessage": "Authentication failed",
"data": null,
"error": {
"message": "Provided API key is invalid or inactive",
"code": "INVALID_API_KEY"
}
}
- Log in to the Trackpilots dashboard and go to Settings → Developer Tools → API Keys.
- Confirm the key you are using is listed and shows an Active status.
- If the key has been deleted or deactivated, generate a new one and update your integration.
PLAN_EXPIRED
This error is returned from every API endpoint when the organisation’s subscription has expired or is on a plan that does not include API access.
{
"success": false,
"statusCode": 401,
"statusMessage": "Upgrade required",
"data": null,
"error": {
"message": "Upgrade required to use Trackpilots APIs",
"code": "PLAN_EXPIRED"
}
}
- The organisation’s paid subscription has expired and has not been renewed.
- The organisation is on the Free (Basic) plan, which does not include API access.
- The subscription is in a payment failure or pending state.
- The API key belongs to an account whose plan has since been downgraded or cancelled.
How to resolve
Step 1 — Check your current plan
Log in to the Trackpilots dashboard and navigate to Settings → Billing. Confirm the subscription status shows Active.
Step 2 — Renew or upgrade
If the plan has expired or is on the Free tier, upgrade to the Starter Pack or higher to re-enable API access.
Step 3 — Verify your API key
After the plan is active, go to Settings → Developer Tools → API Keys and confirm your key is still active. If needed, generate a fresh key and replace it in your integration.
Step 4 — Retry the request
Once the plan is active and the key is valid, all endpoints will resume responding normally. No other changes to your integration are required.
If your plan shows Active in the dashboard but you are still receiving PLAN_EXPIRED, contact support — there may be a sync issue between the billing system and the API gateway.
Handling errors in code
Check the error.code field to handle specific errors programmatically without relying on HTTP status codes alone.
const response = await fetch("https://api.trackpilots.com/v1/...", {
headers: { Authorization: `Bearer ${process.env.TRACKPILOTS_API_KEY}` },
});
const body = await response.json();
if (!body.success) {
switch (body.error.code) {
case "PLAN_EXPIRED":
throw new Error("Trackpilots subscription expired. Please upgrade your plan.");
case "INVALID_API_KEY":
throw new Error("Invalid or inactive API key. Check your credentials.");
case "API_KEY_MISSING":
case "AUTHORIZATION_HEADER_MISSING":
case "INVALID_API_KEY_SCHEMA":
throw new Error("API key is not configured correctly in the request.");
default:
throw new Error(`API error [${body.error.code}]: ${body.error.message}`);
}
}
Error Code Reference
| Code | Status | Cause | Fix |
|---|
AUTHORIZATION_HEADER_MISSING | 401 | No Authorization header sent | Add Authorization: Bearer YOUR_API_KEY |
INVALID_API_KEY_SCHEMA | 401 | Header does not start with Bearer | Use Bearer prefix |
API_KEY_MISSING | 401 | Key value is empty after Bearer | Ensure key is not undefined or blank |
INVALID_API_KEY | 401 | Key is not recognised or deactivated | Regenerate key from the dashboard |
PLAN_EXPIRED | 401 | Subscription expired or Free plan | Upgrade plan from Billing |
Support
For persistent errors after following the steps above:
