Errors
Failed API calls return an HTTP status code. Structured capability errors return their Hydracept error information in a detail object; some standard HTTP errors use a string or validation details in detail.
Typical statuses
| Status | Meaning |
|---|---|
400 | Invalid request / policy rejection |
401 | Missing or invalid Hydracept API key / session |
402 | Budget exceeded |
403 | Your API key, project, or environment is not allowed to make this request |
404 | Capability, job, or resource not found |
409 | Conflict (including idempotency conflicts) |
422 | Request validation failed |
429 | Rate limited |
503 | Provider unavailable |
Structured capability errors
When an endpoint returns a structured capability error, its body has this shape:
{
"detail": {
"code": "BudgetExceeded",
"message": "The request exceeds the configured budget"
}
}
detail.code is the stable Hydracept error code. detail.message is a human-readable explanation. Validation failures may use a different detail shape.
Handle the HTTP status first. When detail.code is present, use that Hydracept value rather than provider-native error strings.
Idempotency
Durable job submits accept idempotencyKey. Replaying the same key with a conflicting payload returns 409 instead of creating a second job.