Errors

Corti uses standard HTTP status codes. 4xx errors indicate a problem with the request; 5xx errors indicate a problem on Corti’s side. Error responses are in JSON and differ between the SDKs and the REST API. The tabs below cover each.

Some Corti products handle errors and authentication differently than what is described below:

Admin API — Separate from the Corti API used for speech to text, text generation, and agentic workflows. See the Administration API reference for details. Please contact us if you have interest in this functionality or further questions.
Agents API — The JSON format of the error response is different. See the Agents API docs for more info.
Embedded Assistant — Authentication is handled differently. See the Embedded Assistant Authentication docs for those methods.

JavaScript SDK
C# .NET SDK
REST API

The SDK throws typed error classes on any non-2xx response or internal failure. Each class exposes a different set of attributes. See Error Handling for full details.

Error Classes

Class	Thrown when	Attributes
`CortiError`	API returned a non-2xx HTTP response (4xx / 5xx)	`message`, `statusCode`, `body`, `rawResponse`
`CortiSDKError`	SDK infrastructure error (e.g. localStorage unavailable)	`message`, `code`, `cause`
`ParseError`	Input validation failed (e.g. missing PKCE verifier, invalid JWT)	`message`, `errors`
`JsonError`	Response body could not be parsed as JSON	`message`, `errors`

HTTP Status Codes

400 — Bad Request

Error code	When it occurs	How to resolve
`bad_request`	The request body or query parameters are malformed or missing required fields.	Double check the fields submitted to be sure of correct format and necessary fields.

401 — Unauthorized

Token endpoint errors are returned as JSON in the response body. Corti API errors are returned in the WWW-Authenticate response header with no body. The header is not accessible from the exception directly; use .WithRawResponse() on the request if you need it.

Error code	When it occurs	How to resolve
`invalid_client`	Client authentication failed. There is a problem with the client ID.	Verify your `client_id` is correct.
`unauthorized_client`	Client authentication failed. There is a problem with the client secret.	Verify your `client_secret` is correct.
`invalid_token`	The bearer token is invalid or has expired. Check the `WWW-Authenticate` header for `error_description`.	Re-authenticate to obtain a fresh token and retry the request.

403 — Forbidden

When it occurs	How to resolve
Accessing a resource (interaction, recording, transcript, document) that belongs to a different client.	Verify the resource ID was created by the authenticated client.

404 — Not Found

Error	When it occurs	How to resolve
`Invalid '{resource_name}' '{resource_id}'`	The requested resource does not exist.	Verify the ID and parent resource ID is correct and was created under the authenticated tenant.

Attempting to access a resource that belongs to a different OAuth client also returns a 404, not a 403. This is intentional. Returning a 403 would confirm that the resource exists, which is a security risk.

429 — Too Many Requests

You have exceeded the rate limit for the API. The SDK automatically retries with exponential backoff. The default retry limit is 2. Override per request:

const response = await client.interactions.create(..., {
    maxRetries: 0, // disable retries for this request
});

If the error persists, reduce request frequency or contact support to discuss your rate limit requirements.

500 — Internal Server Error

An unexpected error occurred on the Corti side. Double check the request format and retry the request. If the issue persists, contact support.

503 — Service Unavailable

The service is temporarily unavailable. Retry with exponential backoff. Monitor the status page.

The SDK throws typed exceptions on any non-2xx response. Each exception extends CortiClientApiException, which exposes Message, StatusCode, and Body. See Error Handling for full details.

Exceptions

Exception class	Thrown when	Attributes
`CortiClientApiException`	Any non-2xx HTTP response	`Message`, `StatusCode`, `Body`

Each status code throws a typed subclass with a more specific Body. See the accordions below for details.

HTTP Status Codes

400 — Bad Request

Exception class	Error code	When it occurs	How to resolve
`BadRequestError`	`bad_request`	The request body or query parameters are malformed or missing required fields.	Double check the fields submitted to be sure of correct format and necessary fields.

401 — Unauthorized

Exception class	Error code	When it occurs	How to resolve
`UnauthorizedError`	`invalid_client`	Client authentication failed. There is a problem with the client ID.	Verify your `client_id` is correct.
`UnauthorizedError`	`unauthorized_client`	Client authentication failed. There is a problem with the client secret.	Verify your `client_secret` is correct.
`UnauthorizedError`	`invalid_token`	The bearer token is invalid or has expired.	Re-authenticate to obtain a fresh token and retry the request.

403 — Forbidden

Exception class	When it occurs	How to resolve
`ForbiddenError`	Accessing a resource (interaction, recording, transcript, document) that belongs to a different client.	Verify the resource ID was created by the authenticated client.

404 — Not Found

Exception class	Error code	When it occurs	How to resolve
`NotFoundError`	`Invalid '{resource_name}' '{resource_id}'`	The requested resource does not exist.	Verify the ID and parent resource ID is correct and was created under the authenticated tenant.

422 — Unprocessable Entity

Exception class	When it occurs	How to resolve
`UnprocessableEntityError`	Request validation failed.	Check `Body` for `Code`, `Description`, `HowToFix`, `Detail`, and `Cause` fields.

429 — Too Many Requests

Exception class	When it occurs	How to resolve
`CortiClientApiException`	Rate limit exceeded after retries exhausted (default: 2 retries with backoff).	Reduce request frequency or contact support to discuss your rate limit requirements.

500 — Internal Server Error

Exception class	When it occurs	How to resolve
`InternalServerError`	An unexpected error occurred on the Corti side. `Body` contains `Detail`, `Type`, `Status`, and `RequestId`.	Double check your request format and retry the request. If the issue persists, contact support.

502 — Bad Gateway

Exception class	When it occurs	How to resolve
`BadGatewayError`	A gateway error occurred. `Body` contains `Detail`, `Type`, `Status`, and `RequestId`.	Retry the request. If the issue persists, contact support.

503 — Service Unavailable

Exception class	When it occurs	How to resolve
`CortiClientApiException`	The service is temporarily unavailable.	Retry with exponential backoff. Monitor the status page.

504 — Gateway Timeout

Exception class	When it occurs	How to resolve
`GatewayTimeoutError`	The gateway timed out. `Body` contains `Detail`, `Type`, `Status`, and `RequestId`.	Retry the request. If the issue persists, contact support.

Resource and API errors (all endpoints except the OAuth token endpoint) return JSON with requestId, status, type, detail, and validationErrors fields:

{
  "requestId": "<string>",
  "status": 400,
  "type": "<string>",
  "detail": "<string>",
  "validationErrors": [
    {}
  ]
}

Authentication errors from the OAuth token endpoint return error and error_description fields:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

HTTP Status Codes

400 — Bad Request

Error code	When it occurs	How to resolve
`invalid_request`	The request is missing a required parameter or is otherwise malformed.	Ensure required fields (`grant_type`,`scope`) are present and correctly formatted.
`unsupported_grant_type`	The `grant_type` value is not recognised by the server.	This API requires a `grant_type` of `client_credentials`. Corti Assistant requires alternate methods for `grant_type`.
`invalid_scope`	The requested scope does not exist or is not permitted for this client.	Use a valid scope. This API requires `openid`.

401 — Unauthorized

Token endpoint errors are returned as JSON in the response body. Corti API errors are returned in the WWW-Authenticate response header with no body. Check the header directly if the response body is empty.

Error code	When it occurs	How to resolve
`invalid_client`	Client authentication failed. There is a problem with the client ID.	Verify your `client_id` is correct.
`unauthorized_client`	Client authentication failed. There is a problem with the client secret	Verify your `client_secret` is correct.
`invalid_token`	The bearer token is invalid or has expired. Check the `WWW-Authenticate` header for `error_description`.	Re-authenticate to obtain a fresh token and retry the request.

403 — Forbidden

When it occurs	How to resolve
Accessing a resource (interaction, recording, transcript, document) that belongs to a different client.	Verify the resource ID was created by the authenticated client.

404 — Not Found

Error	When it occurs	How to resolve
`Invalid '{resource_name}' '{resource_id}'`	The requested resource does not exist.	Verify the ID and parent resource ID is correct and was created under the authenticated tenant.
`'{resource_name}' not found`	The requested resource does not exist.	Verify the ID and parent resource ID is correct and was created under the authenticated tenant.

429 — Too Many Requests

You have exceeded the rate limit for the API. Retry the request after a delay, using exponential backoff. If the error persists, reduce request frequency or contact support to discuss your rate limit requirements.

500 — Internal Server Error

An unexpected error occurred on the Corti side. Double check your request format and retry the request. If the issue persists, contact support.

503 — Service Unavailable

The service is temporarily unavailable. Retry with exponential backoff. Monitor the status page.

Web Socket APIs

REST APIs

Agentic APIs (beta)

Admin APIs

Errors

Error Classes

HTTP Status Codes

Exceptions

HTTP Status Codes

HTTP Status Codes

Web Socket APIs

REST APIs

Agentic APIs (beta)

Admin APIs

Errors

Documentation Index

​Error Classes

​HTTP Status Codes

​Exceptions

​HTTP Status Codes

​HTTP Status Codes

Error Classes

HTTP Status Codes

Exceptions

HTTP Status Codes

HTTP Status Codes