Errors

This page summarizes standard error formats and common failure modes for Carrot API integrations.

Error response format

Typical error payload:

{
  "statusCode": 400,
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "Invalid type on $input.name, expected to be (string)",
      "id": "3f6b0f2c-6d5f-4a3a-9f9a-1c2d3e4f5a6b",
      "timestamp": 1684766595000
    }
  ]
}

code is a SCREAMING_SNAKE enum member — see the table below.
id is a random 36-character identifier in 8-4-4-4-12 hexadecimal form.
timestamp is epoch milliseconds, sent as a JSON number, not a string.
errors currently always contains exactly one entry.

Error codes

HTTP	Code	Meaning
400	`BAD_REQUEST_ERROR`	Request payload failed schema validation.
400	`VALIDATION_ERROR`	Payload is well-formed but breaks a business rule.
401	(gateway)	No `Authorization` header, or a bearer value that is not a decodable JWT.
403	(gateway)	Token parsed but rejected: expired, bad signature, wrong scope or issuer.
403	`RESTRICTED_RESOURCE_ERROR`	Valid token without permission for this resource or environment.
404	`NOT_FOUND_ERROR`	Resource does not exist or is not shared with token owner.
405	`METHOD_NOT_ALLOWED_ERROR`	HTTP method not supported on this path.
409	`CONFLICT_ERROR`	Operation conflicts with existing data — including a replayed `deduplicationId`.
409	`PENDING_PROCESS_CONFLICT_ERROR`	Requested document is still processing. Retry later.
429	(gateway)	Request rate exceeded the client's allowed threshold.
500	`INTERNAL_SERVER_ERROR`	Unexpected server-side failure.
503	`SERVICE_UNAVAILABLE_ERROR`	Service temporarily unavailable or request exceeded processing window.
504	`GATEWAY_TIMEOUT_ERROR`	Upstream timeout/session expiration while completing request.

Rows marked (gateway) are produced by the API edge, not by the service. They carry a plain {"message": "..."} body — no errors[] envelope and no code field — so disambiguate a 403 by the shape of its body, not by its status alone.

For rate limits and quotas, see Rate Limits.

For error recovery patterns and retry strategies, see Error Handling.

Error response format

Error codes

On this page