Error Codes & Handling

Troubleshoot CometAPI request failures with verified guidance for 400, 401, and path errors, plus practical handling for 403, 429, and timeout-class failures.

CometAPI error handling is easiest when you separate request problems, auth problems, and retryable platform issues. This page is the canonical CometAPI error guide and focuses on what you can verify from the client side first.

This guide is based on live checks against the current CometAPI API. We verified 400, 401, and path/base URL failures directly. We did not reproduce 413, 429, 500, 503, 504, or 524 in bounded tests, so the guidance for those statuses is intentionally conservative.

Quick Triage

Status	What it usually means	Retry?	First action
400	Request validation failed before the request was routed successfully.	No	Validate model, messages, JSON shape, and field types.
401	API key is missing, malformed, or invalid.	No	Check Authorization: Bearer <COMETAPI_KEY>.
403	Access was blocked or the current request was not allowed.	Usually no	Retry with a known-good request and remove model-specific fields first.
Path mistake	Wrong base URL or wrong endpoint path. On Comet this may show up as a 301 redirect or HTML, not a clean JSON 404.	No	Use https://api.cometapi.com/v1 exactly and disable auto-follow redirects while debugging.
429	Rate limiting or temporary saturation.	Yes	Use exponential backoff with jitter.
500, 503, 504, 524	Platform or timeout-class failure.	Yes	Retry with backoff and keep the request id.

Error Envelope

The current JSON error envelope returned by CometAPI looks like this:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Many live error messages also include a request id inside error.message. Save that value when you need support.

400 Bad Request

What we observed from the live API when model was omitted:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

In practice, 400 usually means the request body failed validation before the platform could route it to the model provider.

Common causes:

• Missing required fields such as model or messages
• Invalid JSON shape
• Sending a field with the wrong type
• Reusing provider-specific parameters that the selected endpoint does not accept

What to do:

1. Start from a minimal known-good request.
2. Add optional fields back one by one.
3. Compare the request body against the endpoint schema in the API reference.

Minimal known-good example:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Replace your-model-id with any current model ID from the CometAPI Models page.

401 Invalid Token

What we observed from the live API with an invalid key:

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

What to check:

1. The header must be exactly Authorization: Bearer <COMETAPI_KEY>.
2. Make sure your app is not loading an old key from .env, shell history, or a deployed secret store.
3. If one key fails and another key works on the same request, treat this as a token issue, not an endpoint issue.

403 Forbidden

We did not reproduce a stable 403 in bounded tests, so avoid treating a single old message template as the whole story.

On the current Comet documentation, 403 is most often discussed as one of these situations:

• The request is blocked by a platform-side rule such as WAF filtering
• The token or route is not allowed to use the requested model or request shape
• The chosen model rejects one of the advanced parameters you passed

What to do first:

1. Retry with a very simple text request against a known-good model.
2. Remove advanced fields and provider-specific parameters, then add them back gradually.
3. If the response includes a request id, keep it before contacting support.

If the message mentions internal terms such as group or channel, treat those as routing details, not as the first thing to diagnose from the client side. The practical fix is still to validate the token, model, and request shape first.

Wrong Base URL Or Wrong Path

This is the area where the old page was least accurate.

In live checks against the current Comet endpoints:

• Posting to https://api.cometapi.com/chat/completions returned a 301 redirect to https://www.cometapi.com/chat/completions
• Posting to a fake API route such as https://api.cometapi.com/v1/not-a-real-endpoint also returned a 301 redirect to https://www.cometapi.com/v1/not-a-real-endpoint

That means a path mistake may surface as:

• A redirect
• A non-JSON HTML response if your client follows redirects
• A parsing error inside your SDK
• A request that never reaches the API layer cleanly

Use this base URL exactly:

https://api.cometapi.com/v1

Recommended checks:

1. Confirm the base URL includes /v1.
2. Confirm the endpoint path matches the documentation exactly.
3. Disable automatic redirect following while debugging path problems.

413 Request Entity Too Large

We did not reproduce 413 in a bounded test, even with an oversized 8 MiB JSON request body, so the old explanation that the prompt was too long was too narrow.

If you do see 413, treat it as a request size problem first. Common suspects are:

• Large base64 payloads
• Oversized images or audio embedded inline
• Very large multipart or JSON bodies

What to do:

1. Reduce or compress attached content.
2. Split large jobs into smaller requests.
3. Do not assume plain text length is the only cause.

429 Too Many Requests

We did not reproduce 429 during a bounded concurrency probe of 24 parallel GET /v1/models requests, so the exact threshold clearly depends on the route, model, and current platform state.

Treat 429 as retryable:

1. Use exponential backoff with jitter.
2. Reduce burst concurrency.
3. Keep request logging on so you can see which route and model are saturating first.

For a reusable retry pattern, see the backoff example on Chat Completions.

500, 503, 504, And 524

We did not reproduce these statuses in bounded tests. They should be documented as server-side or timeout-class failures, not as user mistakes.

Practical guidance:

• 500: internal platform or provider-side failure
• 503: route or provider service temporarily unavailable
• 504 and 524: timeout-class failures between the platform, edge, or provider service

What to do:

1. Retry with backoff.
2. Keep the request id, endpoint, model, and timestamp.
3. If the same failure repeats across multiple retries, contact support with that context.

Before You Contact Support

Capture these details first:

• HTTP method
• Endpoint path
• Model name
• Sanitized request body JSON (this is the single most useful item for most API calls)
• Query parameters if the failing request used them
• Exact response body if your client captured it
• Full HTTP status
• The exact error.message
• Any request id
• Approximate timestamp
• Whether the same request works with another model or another token

If the failing route accepts file uploads (image editing, audio upload, video generation, etc.) instead of a plain JSON body, send the equivalent submitted payload:

• Field names and text values you sent alongside the file
• File name, file type, and approximate file size
• Whether the file was uploaded directly, referenced by URL, or embedded as base64

The fastest way to reproduce a bug is the exact sanitized request payload. For most API calls, that means the raw request body JSON. For file-upload routes, that means the field list plus file metadata.

This shortens support turnaround significantly.