200 | The account's active Systems. |
401 | The API key is missing, unknown or expired. code tells the three
causes apart: missing_api_key (no Authorization: Bearer header),
invalid_api_key (unknown or revoked key, or invalid format) and
expired_api_key (expiration date has passed). missing_api_key
{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No API key was provided.",
"hint": "Add an Authorization header in the form: Bearer cap_live_<your_key>",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#missing_api_key",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
invalid_api_key
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "API key is invalid or has been revoked.",
"hint": "Verify the key in your dashboard or generate a new one.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#invalid_api_key",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
expired_api_key
{
"error": {
"type": "authentication_error",
"code": "expired_api_key",
"message": "API key has expired.",
"hint": "Roll the key from the dashboard to generate a new valid one.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#expired_api_key",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|
403 | Authorization refused. code tells apart the refusals the operation returns under this status, and each example shows one. insufficient_scope: the key has neither contacts:read nor webhooks:manage; the refusal names contacts:read. feature_not_available: details.feature names what is missing, the public API in the account's plan (public_api) or Systems, not opened to the API for this account yet (systems). browser_not_allowed
{
"error": {
"type": "authorization_error",
"code": "browser_not_allowed",
"message": "API keys must be used from a server, never from a browser.",
"hint": "The request carries an `Origin` header: call the API from your server, where the key stays secret.",
"doc_url": "https://capturia.io/en/developers/api/v1/errors#browser_not_allowed",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
account_suspended
{
"error": {
"type": "authorization_error",
"code": "account_suspended",
"message": "Access to this account is suspended by the Capturia team.",
"hint": "The refusal comes from the account, not the key. While the suspension lasts, no request is accepted: contact the Capturia team.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#account_suspended",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
feature_not_availablepublic_api
{
"error": {
"type": "authorization_error",
"code": "feature_not_available",
"message": "This feature is not included in your plan.",
"hint": "The rejection comes from the account's plan, not the key. Contact your Capturia advisor to talk it over.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#plan",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"feature": "public_api"
}
}
}
insufficient_scope
{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "This API key does not contain the required scope for this endpoint.",
"hint": "This key is missing the `contacts:read` scope. Create a new key with the \"Read only\" preset or add the scope via the dashboard.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#scopes",
"dashboard_url": "https://capturia.io/platform/dashboard/admin/integrations/api-keys/6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f?tab=permissions",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"required_scope": "contacts:read",
"current_scopes": [
"leads:capture"
],
"suggested_preset": "read_only"
}
}
}
feature_not_availablesystems
{
"error": {
"type": "authorization_error",
"code": "feature_not_available",
"message": "This feature isn't open for this account yet.",
"hint": "Capturia opens it account by account before its launch; the rejection comes from the account, not the key. `details.feature` names it. Contact your Capturia advisor to have it opened.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#plan",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"feature": "systems"
}
}
}
|
429 | Rate limit reached. rate_limit_exceeded: the key's hourly quota is
used up. too_many_attempts: too many invalid keys presented from this
IP address (brute-force protection). In both cases, Retry-After gives
the delay in seconds. rate_limit_exceeded
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded.",
"hint": "Retry after the number of seconds in retry_after_seconds, and consider implementing exponential backoff.",
"doc_url": "https://capturia.io/en/developers/api/v1/rate-limits",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"limit": 100,
"count": 100,
"limit_type": "per_key",
"retry_after_seconds": 42
}
}
}
too_many_attempts
{
"error": {
"type": "rate_limit_error",
"code": "too_many_attempts",
"message": "Too many invalid authentication attempts from this IP.",
"hint": "Wait the period indicated by retry_after_seconds before trying again.",
"doc_url": "https://capturia.io/en/developers/api/v1/authentication#brute-force",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"limit_type": "brute_force",
"retry_after_seconds": 300
}
}
}
|
500 | Unexpected server error. Always include the request_id when contacting support. internal_error
{
"error": {
"type": "server_error",
"code": "internal_error",
"message": "Server error. The Capturia team has been notified.",
"hint": "If this persists, contact support and include the request_id from this response.",
"doc_url": "https://capturia.io/en/developers/api/v1/errors#internal_error",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|
501 | Test keys (cap_test_) aren't served yet: only cap_live_ keys are
accepted. not_implemented
{
"error": {
"type": "server_error",
"code": "not_implemented",
"message": "This feature is not yet implemented.",
"hint": "Check the API documentation for available features and the changelog for upcoming releases.",
"doc_url": "https://capturia.io/en/developers/api/v1/errors#not_implemented",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|
503 | A service the request depends on didn't respond (reading the key, the
account or the plan). The same request will go through once it's back:
retry after the Retry-After delay. service_unavailable
{
"error": {
"type": "server_error",
"code": "service_unavailable",
"message": "Service temporarily unavailable.",
"hint": "Retry after the period indicated by Retry-After.",
"doc_url": "https://capturia.io/en/developers/api/v1/errors#service_unavailable",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|