> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer API Troubleshooting

> Troubleshoot Starfire AI developer credentials, permissions, quotas, request failures, runs, webhooks, and API usage.

# Developer API troubleshooting

Use this guide when a Starfire developer integration fails, returns an unexpected status, or stops receiving asynchronous events.

## Start with the request identifier

When the Developer Platform returns a request identifier, record it with the timestamp and endpoint family. That is the fastest way to connect your application's error with Starfire-side logs and diagnostics.

## Credential rejected

Check:

* the integration is using the intended credential
* the credential has not expired or been revoked
* the application or organization still owns it
* the required permission scope is present
* the owning account/organization still has Developer Platform access

Do not paste the secret credential into support messages.

## Permission denied

A valid credential can still lack permission for a resource or operation.

Compare:

* credential scopes
* organization policy
* resource ownership
* plan entitlement
* feature rollout

Creating a broader credential should not be the first troubleshooting step.

## Rate or usage limit reached

Check the applicable plan quota, credential/application override, concurrent-run limits, and credit state.

If the limit is temporary, respect the retry/reset guidance returned by the active API contract. If a hard credit ceiling is reached, repeated retries will not solve it.

## Run/build accepted but later failed

An accepted asynchronous request only confirms creation. Inspect the run/build/research resource for the final state and failure stage.

## Webhook not received

Determine whether:

1. the Starfire event occurred,
2. a webhook delivery was attempted,
3. the endpoint responded,
4. Starfire scheduled a retry,
5. your consumer rejected or ignored a duplicate/event identifier.

Use webhook delivery history where available rather than recreating the original operation.

## Unexpected duplicate event

Webhook consumers should be idempotent because asynchronous delivery can retry the same logical event.

## High latency

Break down whether latency comes from Starfire API processing, model/provider execution, long-running job state, or your own webhook/consumer infrastructure.

## Broad API failure

If unrelated API clients and endpoints are failing at the same time, operators should check Developer Platform health and the incident system.

<CardGroup cols={2}>
  <Card title="Logs & usage" icon="chart-line" href="/developers/logs-usage">Use request IDs and developer telemetry to investigate one integration.</Card>
  <Card title="Developer administration" icon="gauge-high" href="/admin/developer-platform">Use Control Center for platform-wide developer issues.</Card>
</CardGroup>
