Errors
All API errors return JSON with a nested error object:
{
"error": {
"code": "snake_case",
"message": "Human-readable explanation"
}
}
HTTP status codes
| Status | Meaning |
|---|---|
| 400 | Bad request — invalid JSON or missing required param |
| 401 | Unauthorized — invalid or missing API key |
| 404 | Not found — resource does not exist or is not accessible |
| 409 | Conflict — operation blocked by current state |
| 422 | Validation failed |
| 429 | Rate limited or quota exceeded |
| 500 | Internal server error |
| 503 | Upstream service unavailable |
Error codes
| Code | Status | When |
|---|---|---|
unauthorized |
401 | Missing or invalid Bearer token |
invalid_params |
400 | Required parameter missing |
invalid_request |
400 | Malformed JSON body |
not_found |
404 | Record not found (scoped to your account) |
validation_failed |
422 | Model validation errors on create |
workspace_required |
422 | workspace_id missing on monitors/changes index |
discovery_in_progress |
409 | Workspace discovery blocks the operation |
refresh_throttled |
429 | Monitor check requested too soon |
rate_limited |
429 | Per-minute request limit exceeded |
quota_exceeded |
429 | No checks remaining |
service_unavailable |
503 | Temporary upstream failure |
internal_error |
500 | Unexpected server error |
Retry guidance
| Code | Retry? |
|---|---|
rate_limited |
Yes — wait for Retry-After header (seconds) |
quota_exceeded |
No — upgrade plan or wait for period reset |
refresh_throttled |
Yes — wait for Retry-After |
service_unavailable |
Yes — exponential backoff |
internal_error |
Yes — limited retries with backoff |
Example
curl https://api.competiflow.com/v1/changes \
-H "Authorization: Bearer $COMPETIFLOW_API_KEY"
Response (422 Unprocessable Entity):
{
"error": {
"code": "workspace_required",
"message": "workspace_id is required"
}
}