Error catalog
All error codes returned by the v1 API, with a concrete action hint.
Error envelope
All errors follow this JSON format:
{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "This API key does not have the required scope for this endpoint.",
"hint": "Add the 'leads:capture' scope to your key via the dashboard.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#scopes",
"dashboard_url": "https://app.capturia.io/platform/dashboard/admin/integrations/api-keys/ak_xxx",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {"required_scope": "leads:capture"}
}
}All codes
| HTTP | Code | Type | Doc |
|---|---|---|---|
400 | invalid_encoding | validation_error | encoding |
400 | invalid_request | validation_error | invalid_request |
400 | validation_error | validation_error | validation_error |
401 | expired_api_key | authentication_error | expired_api_key |
401 | invalid_api_key | authentication_error | invalid_api_key |
401 | missing_api_key | authentication_error | missing_api_key |
401 | revoked_api_key | authentication_error | revoked_api_key |
403 | feature_not_available | authorization_error | plan |
403 | insufficient_scope | authorization_error | scopes |
403 | terms_acceptance_required | authorization_error | terms |
404 | resource_not_found | not_found_error | resource_not_found |
409 | confirmation_token_invalid | conflict_error | confirmation_token_invalid |
409 | duplicate_resource | conflict_error | duplicate_resource |
409 | idempotency_conflict | idempotency_error | idempotency |
409 | lead_disqualified | conflict_error | lead_disqualified |
409 | tag_managed_by_capturia | conflict_error | tag_managed_by_capturia |
413 | payload_too_large | validation_error | body-size |
415 | invalid_content_type | validation_error | content-type |
422 | business_rule_violation | business_rule_error | business_rule_violation |
422 | system_not_found | business_rule_error | system_not_found |
429 | rate_limit_exceeded | rate_limit_error | View |
429 | too_many_attempts | rate_limit_error | brute-force |
500 | internal_error | server_error | internal_error |
501 | not_implemented | server_error | not_implemented |
503 | service_unavailable | server_error | service_unavailable |
Codes detailed here
Invalid request invalid_request
Missing headers, body too large, invalid JSON, or malformed query parameter.
Hint — Check Content-Type, body size < 1MB, JSON syntax, and query params.
Validation error validation_error
Malformed payload or missing field. The details.validation_errors[] field lists the faulty JSON Pointer paths.
Hint — Check each path in details.validation_errors[] and fix the payload.
Resource not found resource_not_found
The provided ID does not exist, or is not accessible with this key.
Hint — Check the ID and that the resource belongs to your client.
Invalid confirmation token confirmation_token_invalid
The token returned by preview_campaign or preview_quote_send is invalid, expired (10 minutes), already used, bound to another API key, or the campaign or quote changed since the preview.
Hint — Call the preview (preview_campaign or preview_quote_send) again to get a fresh token, present the summary to the human, and only confirm after their explicit agreement.
Duplicate resource duplicate_resource
Business uniqueness conflict (e.g. email already used for a contact).
Hint — Use PATCH/PUT to update the existing resource instead of POST.
Lead disqualified lead_disqualified
The target lead is disqualified: its stage cannot change until the disqualification is lifted. Moving to a lost stage, or to the disqualification stage, is still accepted.
Hint — Reopen the lead from its record in the dashboard, then retry the request.
Tag managed by Capturia tag_managed_by_capturia
The target tag is a campaign tag (system_key starting with campaign:). Capturia adds it to every lead of the campaign and removes it when the lead changes campaign: it cannot be attached or detached through the API. Filtering on it to count a campaign's leads is the intended use.
Hint — To change a lead's campaign, choose it from the lead's record in the dashboard: the tag follows.
Business rule violated business_rule_violation
The operation is blocked by a business rule (e.g. closed pipeline, archived contact).
Hint — The details field specifies the rule. See the endpoint reference for specific constraints.
System not found system_not_found
The system_id provided to a capture endpoint does not match any active System on this account (unknown UUID or one belonging to another account — the response is identical in both cases). No contact is created.
Hint — Use the UUID of one of your Systems, or omit system_id to target your main System.
Server error internal_error
Capturia bug. The request_id lets our support team retrieve the incident in Sentry.
Hint — Retry after a few seconds. If it persists, contact [email protected] with the request_id.
Not implemented not_implemented
Endpoint reserved for future use (e.g. cap_test_* sandbox key).
Hint — See the reference for alternatives available today.
Service unavailable service_unavailable
Maintenance or temporary degradation of an upstream service.
Hint — Respect the Retry-After header (seconds) before retrying.