Skip to main content

​
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.

Logs & usage

Use request IDs and developer telemetry to investigate one integration.

Developer administration

Use Control Center for platform-wide developer issues.