Error Handling - Clara API

Error Response Format

All errors return a JSON body with at minimum a message field:

{
  "message": "Threshold exceeds company limit",
  "code": "B013"
}

Some endpoints return additional context in a details array or an error string field depending on the API version.

HTTP Status Codes

Code	Meaning	What to do
`200`	Success	—
`400`	Bad request — invalid parameters or missing required fields	Fix the request body or query parameters before retrying
`401`	Unauthorized — missing, expired, or invalid Bearer token	Refresh your token and retry
`403`	Forbidden — valid token but insufficient permissions	Check the user role (requires Administrator or the relevant scope)
`404`	Not found — resource does not exist	Verify the UUID or path parameter
`422`	Unprocessable entity — request is well-formed but fails business validation	Check the `code` field for the specific Clara error code
`429`	Rate limit exceeded	Back off and retry with exponential backoff (see Rate Limits)
`500`	Internal server error	Retry once after a short delay; if persistent, contact support
`511`	Network authentication required	Your mTLS certificate is missing or not being sent — check your client cert configuration

Response body examples by status code

400 — Bad request (invalid parameter)

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid date format: startDate must be YYYY-MM-DD",
  "timestamp": "2024-03-15T10:30:00Z"
}

401 — Unauthorized (expired token)

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "timestamp": "2024-03-15T10:30:00Z"
}

403 — Forbidden (insufficient role)

{
  "code": "FORBIDDEN",
  "message": "Access denied: insufficient permissions for this resource",
  "timestamp": "2024-03-15T10:30:00Z"
}

404 — Not found

{
  "code": "NOT_FOUND",
  "message": "Card with UUID '1614c41b-8eb4-4573-9262-8aff011224c5' not found",
  "timestamp": "2024-03-15T10:30:00Z"
}

422 — Business validation failure

{
  "code": "B013",
  "message": "Threshold exceeds company limit",
  "timestamp": "2024-03-15T10:30:00Z"
}

500 — Internal server error

{
  "code": "B033",
  "message": "Core service failure",
  "timestamp": "2024-03-15T10:30:00Z"
}

Auth Errors (401 / 403)

401 — Token expired

Tokens have a finite lifetime (expires_in seconds). When one expires, every request returns 401.

{ "message": "Unauthorized" }

Fix: Request a new token from /oauth/token and retry. In production, refresh proactively before expiry rather than waiting for a 401.

401 — Missing certificate

If the mTLS handshake fails because no client certificate is presented:

{ "message": "Unauthorized" }

Fix: Ensure --cert and --key are included in every request. See Troubleshooting for certificate debugging steps.

403 — Insufficient role

A valid token from a user role that doesn’t have access to the endpoint. Fix: Confirm the API user has the COMPANY_OWNER or required role. Role requirements vary by endpoint.

Business Error Codes

Clara API returns business-specific error codes for validation failures. These appear in the code or message field of the response body.

Cards

Code	Message	Cause	Fix
`B013`	Threshold exceeds company limit	The card `threshold` exceeds the company’s available credit line	Set a lower threshold or contact your Clara account team to review credit limits
`B022`	User is not activated	The target user hasn’t completed email verification or 2FA setup, or the user has been deleted	Verify the user is active in the Clara platform before issuing a card
`B033`	Core service failure	Internal processing failure	Retry after a short delay; if persistent, contact integration support
—	This user already has a card in the creation queue. Try again in 2 minutes	Concurrent card creation for the same user is not allowed	Wait for the in-progress creation to complete or timeout (~2 min) before retrying

Users

Scenario	Status	Cause
Tax ID format invalid	`400`	Tax ID must match country format: MX = 11 or 13 chars, BR = 11 digits, CO = 7–10 digits
Duplicate email	`400`	A user with that email already exists in the company

Transactions / Filtering

Scenario	Status	Cause
Invalid date format	`400`	Dates must be `YYYY-MM-DD`. Use ISO 8601 — no slashes or other separators
`startDate` > `endDate`	`400`	Date range is invalid — start must be ≤ end

Digital Account (Brazil)

Scenario	Status	Cause
Invalid `transactionTypeName`	`400`	Must be one of: `PIX`, `TED`, `BILL`, `TRANSACTION`
Invalid date format	`400`	Must be `YYYY-MM-DD`
`startDate` > `endDate`	`400`	Start date must be ≤ end date

Rate Limits

Requests are rate-limited per client certificate across all endpoints. Limits are applied separately to read (GET) and write (POST, PATCH, DELETE) operations — write endpoints have lower limits. When you exceed the limit, the API returns 429 Too Many Requests:

{ "message": "Too Many Requests" }

Retry strategy: Use exponential backoff with jitter. A safe starting point:

import time, random

def request_with_retry(fn, max_retries=4):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code != 429:
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
    raise Exception("Rate limit exceeded after retries")

For sustained high-volume use cases, contact your Clara integration team to discuss limit increases.

Retry Guidance

Status	Retry?	Notes
`400`	No	Fix the request first
`401`	Yes — after refresh	Refresh token, then retry once
`403`	No	Permission issue — retrying won’t help
`404`	No	Resource doesn’t exist
`429`	Yes — with backoff	Wait before retrying
`500`	Yes — once	Retry after 2–5 seconds; escalate if persistent
`511`	No	Certificate configuration issue

Support Contacts

If you encounter persistent errors not covered here:

Country	Integration Support
Mexico	integration.support.mx@clara.team
Brazil	integration.support.br@clara.team
Colombia	integration.support.co@clara.team

​Error Response Format

​HTTP Status Codes

​Response body examples by status code

​Auth Errors (401 / 403)

​401 — Token expired

​401 — Missing certificate

​403 — Insufficient role

​Business Error Codes

​Cards

​Users

​Transactions / Filtering

​Digital Account (Brazil)

​Rate Limits

​Retry Guidance

​Support Contacts