Guides

Errors

HTTP status codes the API returns, what each one means, and how to troubleshoot the most common one - 401 Unauthorized.

Status	Meaning
`2xx`	Success
`400`	Bad request - the request failed validation (a missing required field, an invalid or duplicate value, or a malformed body)
`401`	Unauthorized - invalid or missing Bearer token
`403`	Forbidden - you don't have access to this record (for example a task that belongs to someone else)
`404`	Not found - no record with that id, or an unknown object type in the URL
`409`	Conflict - the request clashes with the record's current state (for example deleting a company that still has deals attached)
`415`	Unsupported media type - the request's `Content-Type` isn't accepted (for example a `PATCH` sent without `application/merge-patch+json`)
`500`	Server error

If you see a 401, first double-check the token - a typo or the wrong environment's token is the most common cause. Generate a new token from your profile page only if you suspect the token has been leaked or you need to rotate it as part of a security review.

401 response body

{
  "message": "Unauthorized access",
  "path": "/api/v1/objects/contact/records",
  "timestamp": "2026-07-02T08:26:39.437256781"
}

Error response shape

Most errors return a JSON body of this shape:

{
  "code": "VALIDATION_FAILED",
  "message": "Field 'email' is required",
  "errors": [ ... ],
  "path": "/api/v1/objects/contact/records",
  "timestamp": "2026-07-02T08:48:05.199294005"
}

The code at the top tells you what kind of error it is: VALIDATION_FAILED on a 400, NOT_FOUND on a 404, CONFLICT on a 409. The errors list names the individual fields that were wrong, which the next section covers. It is always there, but it is empty when the problem is not about particular fields. Sign-in and access errors are shorter and carry no code: a 401 says "message": "Unauthorized access" and a 403 says "message": "Access denied", each with just path and timestamp.

Validation errors (400)

A 400 comes in two kinds. The common one is a problem with a field you sent: the code is VALIDATION_FAILED, and each entry in the errors list carries its own code saying what went wrong.

Sub-code	Cause	Example message
`REQUIRED_FIELD_MISSING`	A required field was not included in the request	Field 'email' is required
`DUPLICATE_VALUE`	A unique field already has this value on another record	Field 'email' must be unique. Value 'ada@example.com' already exists (conflicting record ID: 1012888).
`INVALID_FIELD`	A field was given a value it doesn't accept	Field 'stage_id' is invalid.
`UNKNOWN_FIELD`	The payload named a field that isn't on the object's schema	Unknown field 'emial'
`MAX_LENGTH_EXCEEDED`	A value is longer than the maximum configured for that field	Field 'name' exceeds its maximum length
`INVALID_SORT_FIELD`	The `sort` parameter named a field that can't be sorted on (list and find)	Cannot sort by 'foo'

The other kind is a request Dreamteam could not read at all: a body that is not valid JSON, a query parameter of the wrong type, or a required parameter you left off. These also return 400, but the code is COMMON-1000, the message is a short note about what could not be read, and there is no errors list.

Use the Schema endpoint to check required, unique, and allowed values before writing.

404 causes

NOT_FOUND can mean either the record id doesn't exist for that object type, or the object type in the URL is invalid (e.g. contacts plural instead of contact). Double-check that object types are singular and that the id exists.

Was this page helpful?