Skip to main content

Error Response Format

All errors follow a consistent structure:
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional context (structure varies by error type)
    },
    "doc_url": "https://docs.precital.com/errors#ERROR_CODE"
  }
}

Error Codes

Missing or invalid API key.Solution: Ensure you’re including a valid API key in the X-API-Key header.
The provided API key is invalid or expired.Solution: Generate a new API key from your account settings.
Insufficient credits for the operation.Solution: Purchase credits from your Precital account or wait for credits to be added.
Request validation failed (missing required fields, invalid format, etc.).Solution: Check the error details for specific field validation issues.
The requested resource was not found.Solution: Verify the resource ID and ensure it belongs to your workspace.
An error occurred with an upstream AI provider.Solution: Retry the request. If the issue persists, contact support.
Rate limit exceeded.Solution: Wait for the time specified in the Retry-After header before retrying.

Example Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Either audio_url or audio_id must be provided",
    "details": {
      "field": "audio_url"
    },
    "doc_url": "https://docs.precital.com/errors#VALIDATION_ERROR"
  }
}

HTTP Status Codes

Status CodeDescription
200Success
400Bad Request (validation error or insufficient credits)
401Unauthorized (missing or invalid API key)
402Payment Required (insufficient credits)
404Not Found
429Too Many Requests (rate limit exceeded)
500Internal Server Error (provider error)