Growth Studio OpenAPI Integration Guide · 错误与重试
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.
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.
429 or retryable 5xx responses, use exponential backoff and honor Retry-After.