Errors

API v2 returns structured error objects inside an error key.

Error shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are invalid. Please check and try again.",
    "details": {
      "issues": [
        { "field": "email", "message": "Please enter a valid email address." }
      ]
    }
  }
}

Field	Description
`code`	Machine-readable error code
`message`	Human-readable summary
`details`	Optional extra context (validation issues, retry hints)

Error codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Valid key but insufficient permission
`NOT_FOUND`	404	Resource does not exist
`VALIDATION_ERROR`	400	Invalid request body or parameters
`BAD_REQUEST`	400	General bad request
`CONFLICT`	409	Operation conflicts with existing data
`TOO_MANY_REQUESTS`	429	Rate limit exceeded
`INTERNAL_SERVER_ERROR`	500	Unexpected server error

Validation errors

When request validation fails, details.issues lists each problem:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are invalid. Please check and try again.",
    "details": {
      "issues": [
        { "field": "firstName", "message": "Required" },
        { "message": "Unknown field: foo. Only documented fields and cf_* keys are allowed." }
      ]
    }
  }
}

Retry guidance

429 — Back off and retry after the window in RateLimit-Reset
500 — Retry with exponential backoff
400 / 409 — Fix the request; retrying without changes will fail

Overview

Objects

Reference

Errors

Errors

Error shape

Error codes

Validation errors

Retry guidance

​Errors

​Error shape

​Error codes

​Validation errors

​Retry guidance

Errors

Error shape

Error codes

Validation errors

Retry guidance