Errors & Status Codes

TrackSERPs uses standard HTTP response codes accompanied by structured, machine-readable JSON error bodies for reliable programmatic error handling.

The Error Envelope

All error responses return a standardized JSON object containing a machine-readable code, human-readable message, and a unique request_id:

Standard Error Response

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to start check run. Required 42, available 10.",
    "request_id": "req_7ef28d9c12344a56b829"
  }
}

Validation Errors (422)

When a request payload fails schema validation, unknown fields are submitted, or parameters violate constraints, the API returns HTTP 422 Unprocessable Content with a fields dictionary detailing each problematic property:

422 Validation Error Response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "req_val987123",
    "fields": {
      "keywords": "At least one keyword must be provided.",
      "keywords.0.tracked_urls.0.match": "Invalid enum value. Expected 'exact' | 'prefix' | 'domain'."
    }
  }
}

Status & Error Codes Reference

Below is the exhaustive matrix of status codes and machine-readable error codes defined in the platform contract:

Status	Error Code	Description & Troubleshooting
`400 Bad Request`	`bad_request`	Malformed JSON body or invalid HTTP query parameters.
`400 Bad Request`	`key_in_query`	API key was passed in the URL query string. Must be sent via `Authorization: Bearer <key>`.
`401 Unauthorized`	`unauthorized`	Missing or invalid API token. Check key prefix and secret.
`401 Unauthorized`	`key_expired`	The token has passed its configured expiration timestamp.
`401 Unauthorized`	`key_revoked`	The key was explicitly revoked or its rotation grace period ended.
`402 Payment Required`	`insufficient_credits`	Account has insufficient check credits to queue the manual run or add keywords.
`403 Forbidden`	`forbidden_scope`	The API key lacks the scope required for this endpoint (e.g. `keywords:write`).
`403 Forbidden`	`ip_not_allowed`	The client IP address is not included in the key's IP allowlist.
`403 Forbidden`	`plan_required`	Account does not have an active subscription or positive credit balance.
`404 Not Found`	`not_found`	Resource does not exist, or the key is restricted to other project IDs.
`409 Conflict`	`conflict`	Resource already exists or concurrent update conflict.
`409 Conflict`	`idempotency_mismatch`	The provided `Idempotency-Key` was previously used with a different request body.
`422 Unprocessable Content`	`validation_error`	Schema validation failed. Check the `fields` object in the response.
`429 Too Many Requests`	`rate_limited`	Per-minute request limit exceeded for this key. Respect `Retry-After`.
`429 Too Many Requests`	`quota_exceeded`	Account has reached its monthly API call allowance.
`429 Too Many Requests`	`run_too_soon`	Manual check runs are limited to once per hour per project. Respect `Retry-After`.

Troubleshooting with Request IDs

Every API response (both successful and error) includes an X-Request-Id header and error body property (e.g. req_7ef28d...). When contacting TrackSERPs developer support, always provide the request ID so our team can trace the log stream.