Errors
Error formats, status codes, and machine-readable error codes.
Response shapes
Errors come in two shapes.
Simple errors use the standard shape:
{
"statusCode": 404,
"message": "Lead not found",
"error": "Not Found"
}Domain validation errors return 400 with a structured errors array. Each entry has a path into your request body, a machine-readable code, a human-readable message, and sometimes an options array with the accepted values:
{
"message": "Validation failed",
"errors": [
{
"path": ["questionAnswerPairs", "0", "question"],
"code": "question_mismatch",
"message": "Question does not match any question on the lead.",
"options": ["Describe your recent experience with similar projects"]
}
]
}Quota and billing errors return a code at the top level:
{
"message": "Proposal limit reached. Usage resets on Aug 1, 2026.",
"code": "proposal_limit_reached",
"currentUsage": 500,
"limit": 500,
"currentPeriodEnd": 1754006400
}Status codes
| Status | Meaning |
|---|---|
400 | Invalid request: schema violation, question mismatch, or inconsistent bidding config. |
401 | Missing or invalid API key, or the organization's subscription is inactive or billing collection is paused. |
402 | A plan limit was hit (proposal quota) or the operation requires a paid plan. |
404 | Campaign, lead, or webhook not found. |
409 | Conflict: the lead was already bid on. |
500 | Unexpected server error. Retry with backoff; if it persists, contact support. |
Error codes
| Code | Status | Meaning |
|---|---|---|
question_mismatch | 400 | A screening question does not verbatim-match the lead's questions. Use the options array to correct it. |
rate_percentage_required | 400 | The selected rate strategy needs biddingHourlyRatePercentage. |
fixed_rate_required | 400 | The fixed_rate strategy needs biddingFixedHourlyRate. |
proposal_limit_reached | 402 | The plan's proposal quota is used up for this billing period. |
subscription_paused | 402 | Billing collection is paused; resume it in Settings, then Billing. |
subscription_inactive | 402 | No active subscription. |
One auth quirk to note
On the Public API itself, subscription problems surface as 401 (the key stops authenticating).
The 402 subscription codes appear on management operations such as creating keys or webhooks.