Skip to main content
Every error response from the Cativa API follows the same format, based on the RFC 7807 Problem Details standard. This page describes that format and the HTTP codes you can encounter.

​
Standard error shape

{
  "type": "Validation.Email.Invalid",
  "status": 400,
  "title": "Validation Error",
  "detail": "The request failed validation.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}
FieldTypeDescription
typestringStable error type identifier. Use to branch logic on your side.
statusnumberHTTP code echoed in the body (RFC 7807 compatibility).
titlestringShort error category (Validation Error, Not Found, Forbidden, Internal Server Error, etc.).
detailstringEnglish message describing the problem. Don’t display directly to end users.
traceIdstringCorrelation id for debugging. Include in any support ticket.
For validation responses, an additional errors field may be populated with per-field errors in the format Dictionary<string, ProblemDetailsFieldError[]>.

​
Common HTTP codes

StatusTitleWhat it meansWhat to do
400Validation Error or Business ErrorBody invalid in format (malformed JSON, wrong content-type) or business rule violated.Fix the request before retrying.
401—Missing, invalid or expired token.Renew/generate a new credential. Don’t retry without action.
403ForbiddenToken is valid but lacks permission for the operation.Check API Key or OAuth scope.
404Not FoundResource doesn’t exist.Confirm id.
422Unprocessable EntityBody well-formed but entity invalid (domain rules).Read detail and adjust.
500Internal Server ErrorCativa-side error.Retry with backoff. If it persists, open a ticket with the traceId.
502/503/504—Transient unavailability.Retry with exponential backoff.

​
Example 400 Validation Error

{
  "type": "Validation.User.Email.Required",
  "status": 400,
  "title": "Validation Error",
  "detail": "Email is required.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}

​
Anti-pattern: ignoring traceId in logs

Always log traceId together with any API error you catch. Without it, the Cativa support team cannot investigate your case — it’s like asking for help without saying what error happened. Include traceId, HTTP status and type in your logger from day one.

​
How to report an error

When opening a ticket at dev@cativa.digital, always include:
  1. The traceId returned in the error response body.
  2. The type and the status of the error.
  3. A sample of the request (URL, method, relevant headers — don’t expose the full key).
  4. Approximate time (with timezone) when the error happened.
Those details let the team correlate with internal logs quickly.

​
Next steps

Identity and Users

Where you’ll see 400 Validation Error (invalid field) most often.

Webhooks

How X-Cativa-Execution-Id helps you deduplicate redelivered webhooks.