Errors

Error response format

Errors follow the JSON:API convention: a top-level errors array, where each entry describes one problem.

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid input",
      "detail": "/data/attributes/email: invalid email",
      "source": { "pointer": "/data/attributes/email" }
    }
  ]
}

Field	Description
`status`	The HTTP status code, as a string (e.g. `"422"`)
`title`	Short error category. Present on validation errors (`"Invalid input"`); omitted otherwise
`detail`	Human-readable explanation. May be `null` on unexpected `5xx` errors
`source.pointer`	JSON Pointer to the offending field (validation errors only)

Errors other than validation return the minimal shape, just status and detail:

{
  "errors": [
    {
      "status": "400",
      "detail": "Duplicate record found"
    }
  ]
}

Most often a duplicate record: a unique field (such as a person's email or a company's domain) collides with an existing record. Pre-match against existing records and route duplicates through PATCH instead of POST.

Other triggers:

Scenario	Fix
Duplicate record	Match existing records first, then PATCH instead of POST
Numeric value out of range	Values must fit a `DECIMAL(16, 4)` column
Malformed JSON body	Check the request body parses as valid JSON
Missing workspace slug	Include the workspace in the URL path

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: the record ID doesn't exist.

Bulk PATCH: one or more IDs in the batch don't exist. The endpoint pre-validates every ID and rejects the whole batch before applying any changes, so a partial update can't happen.

Workspace: the workspace slug in the URL doesn't exist ("Workspace not found").

Object: the {object} path segment isn't a known or custom object.

URL: missing /v1 in the URL path.

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

409 Conflict

The schema is being modified by another request ("Schema is being modified by another request. Please retry."). This can surface when concurrent requests add fields or custom objects to the same workspace. Retry after a short delay.

422 Unprocessable entity

Validation failure. The detail names the offending field via a JSON Pointer (e.g. /data/attributes/email: invalid email). Common triggers:

Scenario	Fix
`id` field in POST payload	Remove `id`: it's auto-generated on create
System field in `attributes`	Don't send `_`-prefixed fields (e.g. `_created_by`)
Enum value doesn't match	Match the exact casing: `"Active"` not `"active"`
Invalid email format	Validate the email before sending
`date-time` instead of `date`	Use `format: "date"` for date fields

429 Too many requests

You've sent requests faster than the API will accept. Wait for the period in the Retry-After header, then retry. See Rate limits for the limit, response headers, and an exponential-backoff example.

500 Internal server error

An unexpected error on our side. The detail field may be null. Retry with backoff; if it persists, contact support@clarify.ai with the request path and time.