Preview documentation. The interface is being rolled out — examples are indicative, and we will confirm final values at launch.
Errors (Problem Details)
All Commerce API v1 errors are returned as application/problem+json (RFC 9457).
With a uniform structure you can handle errors generically: first by HTTP
status, then by the code field.
Error response format
| Field | Meaning |
|---|---|
type |
URI identifying the problem type |
title |
Short human-readable description of the error type |
status |
HTTP status code (duplicated in the body) |
code |
Stable machine-readable error identifier (handle by this) |
detail |
Description of this specific occurrence |
instance |
URI/identifier of this specific occurrence |
correlation_id |
Identifier for support correlation |
errors |
List of detailed errors (e.g. per field on validation) |
Handle errors by the code field, not by title/detail text — copy may
change; codes are stable within v1.
Error code catalog
| Status | code |
When it occurs |
|---|---|---|
| 401 | invalid_signature |
Invalid signature or inconsistent headers |
| 401 | expired_timestamp |
Timestamp outside the replay window (300 s) |
| 401 | replay_nonce |
Nonce already used in the replay window for this key |
| 403 | insufficient_scope |
Key lacks the scope required for the operation |
| 404 | resource_not_found |
Resource does not exist or is unavailable for the key |
| 409 | idempotency_key_reused |
Same Idempotency-Key with a different body hash |
| 409 | stale_source_version |
source_version older than stored |
| 413 | payload_too_large |
Body exceeds the allowed size |
| 422 | validation_failed |
Invalid body — details in errors |
| 429 | rate_limited |
Rate limit exceeded — see Retry-After header |
| 503 | tenant_unavailable |
Temporary unavailability — retry after Retry-After |
Statuses 401/403 are covered in Authentication;
409 conflicts in Idempotency. Limits and 429/413 are
in Pagination and limits.
Example error body
HTTP/1.1 422 Unprocessable Entity Content-Type: application/problem+json{ "type": "https://api.callbotagent.ai/problems/validation-failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Field customer.phone has an invalid format.", "instance": "/api/v1/commerce/orders", "correlation_id": "corr_3f9a12c7", "errors": [ { "field": "customer.phone", "code": "invalid_format", "message": "E.164 format required." } ] }
if (!res.ok) {
const problem = await res.json(); // application/problem+json
handleByCode(problem.code, problem.correlation_id);
}if ($response->getStatusCode() >= 400) {
$problem = json_decode((string) $response->getBody(), true);
handle_by_code($problem['code'], $problem['correlation_id']);
}Correlation ID and support tickets
The correlation_id field uniquely identifies the error occurrence on our side.
Save it in your logs and include it when contacting support — it speeds up
diagnosis. Do not include the key secret or customer PII in tickets; correlation_id,
code, and timestamp are enough.