Get Started
Errors and Rate Limits
Common error envelopes, status codes, and throttling behavior.
Error envelopes
Steve does not use a single global error envelope across every surface. The response shape depends on the route family.
| Surface | Error shape |
|---|---|
| External Integration API | { "error": "..." } |
| Workflow Agent API | { "error": "..." } |
| Invitation validate | { "valid": false, "error": "..." } for semantic failures, { "valid": false, "error": "missing_token" } for missing token |
| Invitation complete | { "success": false, "error": "..." } |
Status code matrix
| Status | Where it appears | Meaning |
|---|---|---|
200 OK | Most successful reads/posts | The request completed successfully |
201 Created | Reserved for future upload-session create endpoints | Resource was created |
400 Bad Request | Invitation routes, agent validation, future submit endpoints | Missing field, malformed body, or invalid state |
401 Unauthorized | API-key and agent routes | Missing, malformed, or invalid credentials |
403 Forbidden | API-key and agent routes | Key revoked, wrong owner, or insufficient role |
404 Not Found | Job polling | Session not found |
410 Gone | Planned upload-session flow | Session expired |
422 Unprocessable Entity | Webhook URL validation and future session validation | Semantically invalid input |
429 Too Many Requests | API-key and agent routes | Caller exceeded a configured rate limit |
500 Internal Server Error | Any surface | Unexpected server-side failure |
External API rate limits
Rate limits are enforced per API key with fixed one-minute windows.
| Limit bucket | Active endpoints | Limit |
|---|---|---|
read | GET /api/v1/companies, GET /api/v1/jobs/{sessionId} | 300 req/min |
webhook_test | POST /api/v1/webhooks/test | 10 req/min |
session | Reserved for planned session-create endpoints | 60 req/min |
submit | Reserved for planned session-submit endpoints | 20 req/min |
Successful responses include:
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset
When a limit is exceeded, Steve returns 429 plus:
Retry-AfterX-RateLimit-LimitX-RateLimit-Remaining: 0X-RateLimit-Reset
Workflow agent rate limit
The private workflow agent is limited to 20 messages per minute per authenticated user.
Retry guidance
For 429 responses:
- Respect
Retry-After. - Add jitter.
- Keep usage below the published ceiling instead of running exactly at it.
The external API uses fixed windows rather than sliding windows, so a burst around a minute boundary can appear uneven. Design for headroom.