Error reference

Every error this API returns is an RFC 9457 problem document (application/problem+json), except one: a request whose headers are larger than the server accepts is refused with 431 and no body, before the API runs. Each type is https://developer.carepatron.com/docs/errors#{code} for one of the codes below, so a type you hold opens the entry describing it.

The code - the fragment at the end of that URI - is the stable, machine-readable identifier for the failure. Branch on the code, not on title or detail, which may be reworded, and not on the whole URI: the code is the part this contract holds immutable, the prefix is not, and it has already moved once. Read the fragment when there is one and the last path segment otherwise, and a prefix change cannot stop your handling firing.

A problem document also carries status, a human-readable title, an occurrence-specific detail, an instance trace identifier to quote when contacting support, and a timestamp. Quote instance when reporting a problem: it identifies the exact request.

Three refusals can come from the edge in front of the API, before a request reaches it: missing_api_key for a request carrying no key, rate_limit_exceeded, and unsafe_request_body. The edge serves each as application/json rather than application/problem+json, with the same type, title, status and detail members, except that the 429's detail is the edge's own, and without instance or timestamp. The edge's 429 carries Retry-After: 300 and no RateLimit-* headers. Any other request the edge refuses is answered by CloudFront rather than with a problem document: one sent over plain http:// or from an address on a reputation list with CloudFront's own 403 page, and one whose headers take it past CloudFront's 32,768-byte limit on a request's path, query string and headers with 494.

A request_validation_failed document carries one further member, errors, holding every constraint the request body broke. Validation errors describes it in full.

Every code an API key can reach is below. Carepatron's own web applications sign in through a browser session instead, and the refusals that produces - api_key_already_revoked among them, which is about revoking a key rather than presenting one - are in the web app error reference.

400 Bad Request

idempotency_key_malformed

Malformed Idempotency-Key

Use an Idempotency-Key of 1 to 255 characters matching ^[A-Za-z0-9_-]+$; a V4 UUID is recommended.

idempotency_key_required

Idempotency-Key header required

Send an Idempotency-Key header - a unique string per logical request, e.g. a V4 UUID - so the request can be safely retried without duplicating its effect.

invalid_cursor

Invalid pagination cursor

Omit the cursor to start from the first page, or send a nextCursor value returned verbatim by a previous page.

invalid_include

Invalid include

Send only include values the published parameter declares for this operation, or omit the parameter for the default response.

invalid_include_archived

Invalid includeArchived parameter

Send includeArchived as true or false, or omit it to list active contacts only.

invalid_pagination_limit

Invalid pagination limit

Send a limit within the published minimum and maximum for this parameter, or omit it to use the default page size.

malformed_request_body

Malformed request body

Send a JSON body matching the published schema for this operation. The schema is closed: a property it does not declare is rejected rather than ignored, so check for a misspelled or unsupported field as well as for invalid JSON.

malformed_tenant_path

Malformed tenant path

The path names a tenant type but no readable tenant id follows it, as in /providers or /providers/. Address the resource under /providers/{providerId}/....

missing_api_version_header

Missing API version

Send a cp-api-version header naming a supported API revision date.

precondition_required

Precondition required

This operation requires the resource's current validator on If-Match. Read the resource, then resend with the ETag it returned.

request_validation_failed

Request body validation failed

One or more properties of the request body break a constraint the published schema declares for them - a length, a format, or a required value. Each item of errors names the property by JSON Pointer and the constraint by code; the operation's schema states what each one accepts. See Validation errors.

unknown_api_version

Unknown API version

Use a cp-api-version header value listed as supported in the API documentation. See API versions.

401 Unauthorized

api_key_mode_mismatch

API key mode does not match this environment

Use a cp_test_ key against the staging host or a cp_live_ key against production.

api_key_rejected

API key rejected

The key was not recognised or has been revoked. Issue a new key if needed.

malformed_api_key

Malformed API key

Use the full API key as issued, including its cp_test_ or cp_live_ prefix.

missing_api_key

Missing API key

Send the cp-api-key header with a key issued for this environment.

unauthenticated

Authentication required

This request was not authenticated. Supply valid credentials for this API and retry.

403 Forbidden

acting_user_no_workspace_access

The user this API key acts for has no access to this workspace

This API key acts on behalf of the user who created it, and that user no longer has access to this workspace, so the operation cannot be authorised. Ask a workspace administrator to restore their access, or issue a new API key from an account that has it.

acting_user_not_permitted

The user this API key acts for is not permitted to do this

This API key acts on behalf of the user who created it, and that user does not hold the permission this operation requires. Ask a workspace administrator to grant it, or issue a new API key from an account that holds it.

acting_user_not_workspace_admin

The user this API key acts for no longer administers this workspace

This API key acts on behalf of the user who created it, and that user is no longer an administrator of this workspace, so the key's authority in it has lapsed. Ask a workspace administrator to restore their administrator role, or issue a new API key from an account that holds one.

insufficient_scope

Insufficient scope

The API key is valid but does not grant the scope required for this endpoint.

ip_not_allowed

Source address not allowed for this App

Call from an address in the App's IP allowlist, or change the allowlist in the Developer Console.

tenant_path_mismatch

Tenant path does not match credential

Address resources under the tenant path that matches your API key's credential.

unsafe_request_body

Unsafe request body

The request was refused before it reached the API, because its body holds text resembling cross-site scripting, such as a script element or a javascript: URL. Remove that text from the request's values and resend.

wrong_token_context

Wrong token context

This endpoint requires a different token context than the one associated with your API key.

404 Not Found

resource_not_found

Resource not found

The URL addresses nothing you can reach: the contact, entry, field or job does not exist in this workspace, or the operation is not available to this workspace. Where a detail is present, it names the id.

405 Method Not Allowed

method_not_allowed

Method not allowed

The path exists but not for this method. The Allow response header lists the methods it accepts.

406 Not Acceptable

not_acceptable

Not acceptable

Accept a JSON response: send an Accept header that names application/json, or none.

409 Conflict

contacts_export_not_ready

Contacts export not ready

Poll the export job status endpoint until it reports Succeeded, then re-request the result. Honour the Retry-After header (default 5s).

contacts_export_row_limit_exceeded

Contacts export exceeds row limit

Narrow the export query so the resulting set fits within the documented row limit.

collection_at_capacity

Collection at capacity

This contact already holds as many entries as this collection accepts. Remove one before adding another.

idempotency_key_conflict

Idempotency-Key reused for a different request

This Idempotency-Key was already used for a request with a different payload. Use a new key for a new request, or resend the original request unchanged.

idempotency_request_in_progress

A request with this Idempotency-Key is still in progress

An earlier request with this Idempotency-Key is still being processed. Retry after a short delay. Honour the Retry-After header (default 2s).

portal_linked_primary_email

The contact's portal login cannot be moved through the API

This contact has portal access, which its primary email address identifies. Designating another address would move the portal login to it and send that address a portal invitation, so the change is made in Carepatron rather than through the API.

primary_email_not_writable_here

Primary email address not writable here

This contact has portal access, which its primary email address identifies, so the address is changed in Carepatron rather than through the API, and the contact's last address cannot be removed.

primary_member_not_removable_here

Primary member not removable here

This entry is the one the contact's primary designation points at, and the set holds others. Designate one of them through its own .../primary route - the detail names this entry's - then remove this one. On a contact with portal access its primary email address is its login, which is changed in Carepatron instead. The only entry of a set can be removed.

resource_conflict

Resource conflict

The request conflicts with the current state of the resource - for example a value that must be unique is already in use. Change the conflicting value and resend.

unsupported_resource_state

Resource state not representable

The resource holds a value or state this version of the API cannot represent or write back. A read that cannot serve it is refused, and so is a write that would be applied over it. Where the detail names a request that repairs it, send that and retry; otherwise contact support with the instance value.

412 Precondition Failed

precondition_failed

Precondition failed

The resource changed since the version this request expected, so it was refused rather than applied over the change. Re-read the resource and resend against its current version.

413 Content Too Large

idempotency_payload_too_large

Request body too large for idempotent processing

The request body exceeds the size the gateway can fingerprint for idempotency. Reduce the payload size and retry.

request_body_too_large

Request body too large

The request body exceeds 1 MiB, the most any request may carry. Reduce the payload size and retry.

415 Unsupported Media Type

unsupported_media_type

Unsupported media type

Send the request body as JSON, with a Content-Type of application/json.

422 Unprocessable Content

validation_failed

Request validation failed

Correct the invalid request fields and resend.

429 Too Many Requests

rate_limit_exceeded

Rate limit exceeded

You have exceeded the request rate limit for this API key. Wait until the window resets (see the Retry-After and RateLimit-Reset response headers) and retry with backoff.

create_budget_exceeded

Daily contact creation budget exceeded

This workspace has sent as many contact create requests through the API as it may in one UTC day, refused and failed ones included. Retry after the budget resets at 00:00 UTC (see the Retry-After response header), or ask Carepatron support to raise the workspace's budget.

500 Internal Server Error

contacts_export_query_failed

Contacts export query failed

Retry with backoff; if it persists, contact support quoting the instance value. Honour the Retry-After header (default 10s).

internal

Internal server error

Retry with backoff. If the error persists, contact support with the instance value from the response. Honour the Retry-After header (default 5s).

malformed_security_context

Malformed security context

Retry with backoff; if it persists, contact support quoting the instance value.

missing_security_context

Missing security context

Retry with backoff; if it persists, contact support quoting the instance value.

502 Bad Gateway

bad_gateway

Bad gateway

The service could not get a valid response from an upstream dependency. Retry with backoff. Honour the Retry-After header (default 5s).

503 Service Unavailable

service_unavailable

Service temporarily unavailable

The service is temporarily unable to process this request. Retry with backoff. Honour the Retry-After header (default 5s).

504 Gateway Timeout

gateway_timeout

Request timed out

The request exceeded the gateway's time limit and was aborted. Retry with backoff; if it persists, reduce the request's scope (e.g. use the async export + poll flow for large result sets). Honour the Retry-After header (default 5s).