Errors

Error response format

{
  "errors": [
    {
      "status": 422,
      "title": "Validation Error",
      "detail": "Duplicate record found for email: jane@example.com"
    }
  ]
}

Common errors

401 Unauthorized

Wrong auth scheme or invalid API key.

Authorization: Bearer YOUR_KEY    ← wrong
Authorization: api-key YOUR_KEY   ← correct

404 Not found

Single record: Record ID doesn't exist.

Bulk PATCH: One or more IDs in the batch don't exist. The endpoint pre-validates all IDs before applying any changes.

URL: Missing /v1 in the URL path.

https://api.clarify.ai/workspaces/acme/...      ← wrong
https://api.clarify.ai/v1/workspaces/acme/...   ← correct

422 Unprocessable entity

Validation failure. Common triggers:

Scenario	Fix
`id` field in POST payload	Remove `id` — it's auto-generated
Enum value doesn't match	Check exact casing: `"Active"` not `"active"`
Invalid email format	Validate email before sending
`date-time` instead of `date`	Use `format: "date"` for date fields

400 Bad request

Duplicate record detected (email or domain collision). Pre-match against existing records and route duplicates through PATCH instead of POST.

500 Internal server error

If you get a 500 when updating a custom object record, use the bulk PATCH endpoint instead of the single-record PATCH. See custom objects for details.