API Errors

Purpose

API clients should treat response status, hasErrors, and validation messages as part of the same error-handling model.

Response Handling

1. Read the HTTP status code.
2. Parse the response body as JSON.
3. Check hasErrors when present.
4. Read data, meta, and error messages according to the endpoint.
5. Log enough context for support without exposing secrets or full document content.

caution

Some xTrakt backend responses are returned with Content-Type: text/plain while the body contains JSON. API clients should parse the response body as JSON even when the content type is not application/json.

Common Conditions

Condition	Likely Cause	Action
401 Unauthorized	Missing, expired, or invalid credential	Refresh token or rotate API key
403 Forbidden	Credential lacks tenant, role, or subscription access	Confirm entitlement and permissions
Validation error	Request body is incomplete or invalid	Correct required fields and retry
Processing error	Document, provider, or service failure	Retry with known-good input and check logs

Related Docs

• API Authentication
• API Examples
• Troubleshooting