Rate limits & errors
A dependable API needs predictable limits and failure behavior. Starfire’s Developer Platform is designed so integrations can distinguish usage limits, permission problems, invalid input, temporary service failures, and long-running job failures.
Rate-limit dimensions
Limits can vary by account, organization, plan, application, or credential and can include concepts such as:
- requests per time window
- concurrent runs
- concurrent FORGE builds
- model throughput
- daily credit usage
Do not assume one universal limit applies to every account or endpoint family.
Error categories
Developer clients should be prepared for categories such as:
- invalid request
- missing permission
- resource not found
- usage or credit limit reached
- rate limit reached
- provider/service unavailable
- run or build failure
The active API contract defines the exact error codes and fields.
Request identifiers
Starfire’s developer architecture associates requests with an identifier that can connect a client-side error to API logs and administrator diagnostics.
When asking for support, include the request identifier and approximate timestamp rather than copying unrelated private payloads.
Retry behavior
Temporary service failures or rate limits can sometimes be retried after an appropriate delay. Invalid input or permission problems should be corrected instead of repeatedly retried.
For state-changing requests, use the documented retry-safe behavior when available so a network interruption does not accidentally create duplicate work.
Long-running failures
Creating a run or build successfully only means the job was accepted. The client should still inspect the final state because validation, tools, providers, or budgets can cause a later failure.
Build resilient integrations
Store enough local context to connect a failure with the Starfire resource involved:
- request identifier
- resource or run identifier
- timestamp
- endpoint family
- final status
Treat observable state as part of the API contract. That makes support and recovery much easier than treating every failure as an unknown exception.
