Error Codes

The Qamera AI API uses standard HTTP status codes to indicate the outcome of each request. Successful requests return 200. Error responses include a JSON body with an error field describing what went wrong.

Response Format

All error responses follow this structure:

{
  "error": "A human-readable description of the problem."
}

Status Codes

200 OK

The request was processed successfully. The response body contains the requested data or confirmation of the completed action.

400 Bad Request

The request body is missing required fields, contains invalid values, or is malformed.

{
  "error": "Validation failed: 'productId' is required."
}

Common causes:

• Missing required fields in a POST body.
• Invalid field types (e.g. string where a number is expected).
• Malformed JSON.

401 Unauthorized

The API key is missing, invalid, expired, or revoked.

{
  "error": "Invalid API key."
}

Common causes:

• No X-Api-Key or Authorization header provided.
• Key has been revoked or has passed its expiration date.
• Typographical error in the key value.

402 Payment Required

The account associated with the API key does not have enough credits to complete the requested operation.

{
  "error": "Insufficient credits. Required: 5, available: 2."
}

What to do:

• Purchase additional credits or a credit pack from your workspace billing settings.
• Check your current balance before submitting generation requests.

403 Forbidden

The API key does not have the required scope for this endpoint.

{
  "error": "Missing required scope: 'content.register'."
}

Common causes:

• The key was issued without the scope needed for the requested action.
• Attempting a POST operation with a read-only key (once content.read scope is available).

404 Not Found

The requested resource does not exist, or your account does not have access to it.

{
  "error": "Product not found."
}

Common causes:

• Incorrect resource ID in the URL.
• The resource belongs to a different account.
• The resource was deleted.

429 Too Many Requests

The API key has exceeded the rate limit of 60 requests per minute.

{
  "error": "Too many requests. Please retry after a short delay."
}

What to do:

• Wait before retrying. Use exponential backoff with jitter.
• See the Rate Limiting page for detailed retry strategies.

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "An internal error occurred. Please try again later."
}

What to do:

• Retry the request after a short delay.
• If the error persists, contact support with the request details and approximate timestamp.

502 Bad Gateway

An external service that the API depends on returned an unexpected response.

{
  "error": "External service returned an unexpected response."
}

Common causes:

• A downstream AI generation service is temporarily unavailable.
• Network issues between Qamera AI and its service providers.

What to do:

• Retry after a few seconds. These errors are usually transient.

503 Service Unavailable

No active content generator is available to process the request.

{
  "error": "No active generator available. Please try again later."
}

Common causes:

• All generation workers are offline or undergoing maintenance.
• Temporary capacity issues during peak usage.

What to do:

• Retry after 30–60 seconds.
• Check the Qamera AI status page for ongoing incidents.

Summary Table