Growth Studio OpenAPI Integration Guide · 错误与重试

Error Responses

Failed requests use standard HTTP status codes and this common envelope:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request contains invalid video or media parameters.",
    "retryable": false,
    "details": {}
  },
  "request_id": "request_abc123"
}
Field Type Description
error.code string Stable error identifier; use this for programmatic handling
error.message string Developer-facing description; do not implement logic by matching message text
error.retryable boolean Whether retrying under unchanged conditions is appropriate
error.details object Additional information; empty when unavailable
request_id string Request tracking ID
HTTP error.code retryable Description
400 INVALID_REQUEST false Invalid JSON, video parameters, image URL, or query parameters
400 INVALID_CURSOR false Invalid or modified cursor, or cursor incompatible with the current filters
400 TEMPLATE_NOT_FOUND false Missing or disabled template; refresh the catalog
400 MODEL_NOT_FOUND false Model not in the current OpenAPI catalog; refresh the catalog
401 INVALID_API_KEY false Missing, incorrect, or unavailable API key
402 INSUFFICIENT_BALANCE false Insufficient workspace wallet balance
403 WORKSPACE_ACCESS_DENIED false The API key's account no longer has workspace access
404 VIDEO_NOT_FOUND false Video is missing or outside the current account and workspace
404 IMAGE_TASK_NOT_FOUND false Missing, inaccessible, or unsupported suite task
409 VIDEO_EDIT_UNAVAILABLE false Video is not currently editable or an edit is already running; query the details
409 MODEL_CATALOG_VERSION_STALE false Refresh the model catalog and rebuild the request
409 TEMPLATE_PRICE_CHANGED false expected_price differs from the current price; refresh template pricing and recalculate
413 PAYLOAD_TOO_LARGE false Image upload exceeds 20 MiB, or variation/suite JSON exceeds 1 MiB
415 UNSUPPORTED_MEDIA_TYPE false Upload is not a supported JPEG, PNG, or WebP image
422 PRODUCT_FETCH_FAILED false Product URL yielded no usable product; try manual input
422 MEDIA_PROCESSING_FAILED false Image processing or content checks failed, potentially involving product text, scripts, or images
422 TEMPLATE_PRICE_UNAVAILABLE false Template cannot be priced for the selected inputs; adjust them or choose another template
429 CONCURRENCY_LIMIT_EXCEEDED true Too many active tasks; wait for existing tasks to finish
429 RATE_LIMIT_EXCEEDED true Current request quota exceeded
500 INTERNAL_ERROR See response Internal service error
503 UPLOAD_FAILED true Temporary image upload failure
503 TEMPLATE_CATALOG_UNAVAILABLE true Template catalog or execution specifications temporarily unavailable
503 MODEL_CATALOG_UNAVAILABLE true Model catalog temporarily unavailable
503 SERVICE_UNAVAILABLE true A dependent service is temporarily unavailable

A Product Image Suites (product image suite) can return HTTP 200 with status=completed even when some or all images failed. Check each image status. Video failures after acceptance are likewise represented in the queried resource; they do not change the earlier 202 response.

Rate Limits and Retries

Limits are shared across service instances and calculated by API key and operation category. Actual quotas depend on runtime configuration and response headers.

A normal response may include:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1784700000

When the quota is exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "The API key has exceeded the request rate limit.",
    "retryable": true,
    "details": {
      "limit": 1000,
      "window_seconds": 60
    }
  },
  "request_id": "request_abc123"
}
Endpoint or operation Reviewed master quota Scope
POST /openapi/v1/image/upload 1,000/minute API key + image upload
POST /openapi/v1/videos 200/minute API key + video creation
POST /openapi/v1/template/videos/generations Shared video-creation 200/minute API key + video creation
POST /openapi/v1/template/generate Shared video-creation 200/minute API key + video creation
POST /openapi/v1/variation/videos/generations Shared video-creation 200/minute API key + video creation
POST /openapi/v1/creation/videos/generations Shared video-creation 200/minute API key + video creation
POST /openapi/v1/product-suite/images/generations 200/minute, shared with ordinary image generation API key + image creation
GET /openapi/v1/product-suite/images/generations/{task_id} 8,000/minute, shared with ordinary image task queries API key + image task query
GET /openapi/v1/video-templates 4,000/minute API key + template catalog
GET /openapi/v1/template/list, GET /openapi/v1/template/tags Shared template-catalog 4,000/minute API key + template catalog
GET /openapi/v1/models 4,000/minute API key + model catalog
GET /openapi/v1/images 4,000/minute API key + image list
GET /openapi/v1/videos 4,000/minute API key + video list
GET /openapi/v1/videos/{video_id} 8,000/minute API key + video detail

Template and model catalog quotas are separate. These are request-rate limits, not limits on concurrently running generation tasks. Use actual response headers when they differ from the reviewed configuration.