Skip to main content
CometAPI error handling is easiest when you separate request-shape problems, auth problems, path mistakes, and retryable platform failures. Use the combination of HTTP status, error.code, and error.message to decide whether to fix the request or retry it.

​
Quick triage

StatusWhat it usually meansRetry?First action
400Request validation failed before the request was processed normally.NoValidate model, messages, JSON shape, and field types.
401API key is missing, malformed, or invalid.NoCheck Authorization: Bearer <COMETAPI_KEY>.
403Access was blocked or the current request was not allowed.Usually noRetry with a known-good request and remove model-specific fields first.
Path mistakeWrong base URL or wrong endpoint path. On Comet this may show up as a 301 redirect or HTML, not a clean JSON 404.NoUse https://api.cometapi.com/v1 exactly and disable auto-follow redirects while debugging.
429Rate limiting or temporary saturation.YesUse exponential backoff with jitter.
500 with error.code: invalid_requestA malformed request surfaced through a server-status response.NoFix the request body before retrying.
500, 503, 504, 524Platform, provider, or timeout-class failure.YesRetry with backoff and keep the request id.

​
Error envelope

Many CometAPI failures use an error body like this: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Some responses leave code empty. When the status is 500, treat error.code and error.message as the deciding signal.

​
400 Bad Request

A 400 usually means the request body failed validation before the request could be processed normally. Common causes:
  • Missing required fields such as model
  • Invalid JSON shape
  • Sending a field with the wrong type
  • Reusing provider-specific parameters that the selected endpoint does not accept
Start from a minimal known-good request, then add optional fields back one by one. Compare the payload against the endpoint schema in the API reference. Use a minimal request like this: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Replace your-model-id with any current model ID from the CometAPI Models page. Do not assume every malformed chat request returns 400. Missing required chat fields such as messages can also surface as 500 with error.code: invalid_request.

​
500 Internal Server Error

Most 500 responses indicate a platform or provider failure. For Chat Completions, some malformed requests can also surface as 500 while still carrying error.code: invalid_request. One example is a request that omits messages: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
If a 500 response has error.code: invalid_request, treat it as a request problem:
  1. Fix the request body.
  2. Compare the payload against the endpoint schema.
  3. Retry only after correcting the payload.
If a 500 response does not point to an invalid request, keep the request id and use backoff.

​
401 Invalid Token

A token failure usually looks like this: 
{
	"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

403 is most often 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

On Comet, 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

If you 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

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.

​
503, 504, and 524

These statuses are server-side or timeout-class failures. Practical guidance:
  • 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 ID
  • 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 most effective 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.