Troubleshooting

Short answers for the most common ingestion problems.

No traces appearing

• API key valid — copy from API Keys page; revoked keys are rejected silently after first 401.
• Correct project — projectId must match your project ID from the API Keys page.
• Telemetry sent — confirm your code runs and reaches the ingest endpoint.
• flush() called — required after trackRequest(); withTrace() flushes automatically.
• Process didn't exit early — await flush() before Node exits (scripts, serverless).

Invalid API key

HTTP 401 with error code auth_failed:

{
  "error": {
    "code": "auth_failed",
    "message": "Invalid API key."
  }
}

Revoked keys return api_key_revoked instead.

Rate limit exceeded

HTTP 429 when sending too fast. Slow down batching or retry after the window:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Ingestion rate limit exceeded. Slow down SDK batching or retry later."
  },
  "details": {
    "window": "per_minute",
    "limit": 120,
    "retry_after_seconds": 60
  }
}

Telemetry rejected

HTTP 422 when payload validation fails:

{
  "error": {
    "code": "payload_invalid",
    "message": "The provider field is required."
  },
  "details": {
    "reason": "validation_failed",
    "errors": {
      "provider": ["The provider field is required."]
    }
  }
}

Local development

Point the SDK at your local PromptLayer instance:

PROMPTLAYER_API_KEY=pl_live_your_key_here
PROMPTLAYER_PROJECT_ID=1
PROMPTLAYER_BASE_URL=https://promptlayer.app

const promptlayer = new PromptLayer({
  apiKey: process.env.PROMPTLAYER_API_KEY!,
  projectId: process.env.PROMPTLAYER_PROJECT_ID!,
  baseUrl: process.env.PROMPTLAYER_BASE_URL,
  debug: true,
})

Enable debug: true to see send results in the console.