Errors - Notealy

All non-2xx responses follow the same shape:

{
  "statusCode": 400,
  "message": "phone must be 10–15 digits, optional leading +",
  "error": "Bad Request"
}

message may be an array when multiple validation errors are returned at once:

{
  "statusCode": 400,
  "message": [
    "name is required and must not be empty",
    "phone must be 10–15 digits, optional leading +"
  ],
  "error": "Bad Request"
}

Common status codes

Status	Meaning	Recovery
`400 Bad Request`	Validation failed	Fix the payload and retry
`401 Unauthorized`	Token missing, invalid, revoked or expired	Issue a new token
`403 Forbidden`	Token is valid but lacks the scope this endpoint requires	Re-issue the token with the right scopes
`404 Not Found`	Resource id does not exist in your organization	Confirm the id and the org the token belongs to
`409 Conflict`	Uniqueness conflict (e.g. duplicate domain) — rare; most write endpoints upsert instead	Read the resource first
`429 Too Many Requests`	Rate limit hit	Wait until `X-RateLimit-Reset`, then retry
`5xx`	Notealy server error	Retry with exponential backoff

Idempotency

Several write endpoints are idempotent by design:

POST /v1/people upserts on phone → email → externalId.
POST /v1/companies upserts on domain.
POST /v1/people/:id/tags only emits contact.tag_added for newly attached tags.

Safe-to-retry responses make it easy to build at-least-once delivery from your side without duplicates on ours.