Troubleshooting

The failures integrations meet most often, from 401 and 400 with code 50 to 429, batches with failed items, archived and deleted records, and encoding traps, each with its fix.

Each answer names the status and the error code you see in the response body. When none fits, write to support.

I get 401

The credentials were refused. The reason is in message, as Access denied (…).:

Unauthorized call. is the reason for a request without credentials. Check that the program sends HTTP Basic auth and that both environment variables are set.
Invalid Api user credentials is the reason for a wrong user name or password, and for the credentials of another space than the one in the URL: the user name starts with the ID of its own space and works only there.
Credentials that worked before: someone pressed Generate New, which replaces the user name and the password. Copy both.

A wrong region is not a cause: the call is forwarded and answers normally. Do not retry a 401 in a loop: every failed sign-in counts, and repeated ones lock the credentials for a while. The quickstart shows the full response, and authentication how credentials are sent and rotated.

I get 400 with code 50

ERROR_NOT_ENOUGH_PERMISSIONS: the application lacks a permission for the call. Open the application's Edit Permissions and give it access to the record type or area. The error reference lists it with HTTP 400: a missing permission does not answer 403. See Permissions and scopes.

I get 400 with code 117 or 118

The query string is wrong:

Code	Name	Typical cause
`117`	`ERROR_PARAMETER_INVALID`	A value the API does not accept, such as `first` above 100, or a parameter sent twice: `Parameter first is duplicated within the query.`
`118`	`ERROR_PARAMETER_UNKNOWN`	A parameter the endpoint does not know, such as `load-only` or `include-deleted` on a request for one record: `Unsupported parameter …`

Send each parameter once. To match several values, put them in one filter[…], separated by raw commas. A request for one record, GET /entities/{Entity}/{id}, takes only expand. The rules are in querying, and every code in the error-code reference.

I get 429

ERROR_TOO_MANY_REQUESTS: the API is limiting the client, or repeated failed sign-ins have locked the credentials for a while. Wait for the seconds in Retry-After, then retry; without the header, back off exponentially. Rate limits and retries shows the retry in code, and plans and limits lists the limits.

My calls are slow

Check the region. A call to another region's host is forwarded to the space's own region. From Central Europe, a call to an eu-central space takes about 0.2 s through its own host, 0.6 to 1 s through us-east and 1.6 to 3.2 s through ap-southeast. Use the host the discovery endpoint returns. The first write of a kind in a space can also take several seconds; allow for it in your timeouts.

A batch answered 200, but records are missing

With rollback-method=1, a batch writes the valid items and answers 200 with "success": false. Its data lists, in input order, the id of each written item and an error object for each failed one. Check success and every item, not only the status.

With the default rollback, one invalid item fails the whole batch: REST answers 422 and nothing is written. In GraphQL, ROLLBACK_ALL answers 200 with errors and no data; use ROLLBACK_FAILED for per-item results. Batch operations shows both.

I cannot update a record that is already invalid

A PATCH validates only the values that change, so it accepts an update to a record that broke a rule earlier, such as an email1 that is not an e-mail address, even when the request repeats that value. A batch-modify update validates the whole record, fields you do not send included, and answers 422 for such an item. Send it with validation-level=2 (skip validation of unchanged fields); see validation.

A contact create answers 422 with code 119

A contact needs first_name or last_name, although the published spec marks only owner_id as required. Opportunities, products and leads need more than the spec marks too; the list is on validation.

Archived or deleted?

They are different:

	Archived	Deleted
How	`PATCH` `is_archived: true`, or an archive action in GraphQL	`DELETE`, or `batch-delete`
In lists	Still returned, with `is_archived: true`; filter on `is_archived` to leave them out	Not returned, unless the list request sends `include-deleted=true`
Back	`PATCH` `is_archived: false`	`batch-restore`

include-deleted works on lists only: a request for one record refuses it with 400, code 118.

Two writes to the same record

Send the revision you read along with your update, and the API refuses a conflicting change: when a field you send has changed since that revision, the update answers 400 with ERROR_SIMULTANEOUS_UPDATE (code 198) and nothing is written. A change to other fields of the record is not a conflict. Read the record again, merge, and send the update with the new revision. Without revision, the last write wins.

On accounts, the check is per field, as above. On some other entities, any older revision is refused.

Can I update a record whose owner is inactive?

Yes. Release 5.9.0 lifted the restriction in the CRM. The API accepts such an update too, and refuses an inactive user as the new owner unless validation-level includes 16 (skip relation checks).

A filter matches nothing

A raw comma in filter[…] separates OR values; %2C is a literal comma inside a value. URLSearchParams and Python requests send %2C, so build such query strings yourself.
A raw + in a query string arrives as a space: dana+test@example.com becomes dana test@example.com. Encode the value.
A dotted filter reaches one related record: filter[owner.email] works, while filter[step.pipeline.name] is refused with 400, code 117 (querying).

Dates do not parse

REST returns date-times with a space between date and time, such as 2026-10-15 09:00:00.000000+00:00; GraphQL returns the same instant with a T. Replace the space with a T before you parse a REST value with an RFC 3339 parser; see dates and time zones.