HappyOyster Open API response structure and error codes, including business codes, typical scenarios, and handling suggestions.
This document describes the response structure and error codes of the HappyOyster Open API. It applies to all Open API endpoints of the Adventure, Directing, and Acting models.
Response structure
Once a request passes gateway authentication (for both business success and business errors), the response always returns HTTP 200 with the following JSON structure as the body:
{
"code": 0,
"message": null,
"data": {}
}
| Field | Type | Description |
|---|---|---|
code | integer | Business return code. 0 means success; a non-0 value means a business error — see the error code list below. |
message | string | null | Human-readable error message. null when code=0. |
data | object | null | Business payload. On success, contains the endpoint-specific response object; on error, usually null. |
Gateway-layer failures such as AK, signature, or timestamp verification are rejected directly, so those responses do not follow this structure and are typically returned with a 4xx / 5xx HTTP status code — see Error code.
Error code list
| code | Description | Typical scenarios & handling |
|---|---|---|
0 | Success | Request succeeded; read data. |
400000 | Invalid request parameters | mode does not match the current model; prompt or firstFrameImage is missing; prompt is too long; creationModel / uploadMode / resolution / aspectRatio / perspective has an illegal value; image or encrypted ID format is invalid. Correct the parameters per the API doc and retry. |
400001 | Failed to fetch or store image URL | The first-frame or reference image URL is inaccessible or expired. Verify URL accessibility and validity, then retry creating the World. |
401010 | ticket invalid or expired | Enter travel (enter-travel). Call get-travel-credential again to obtain a new ticket. |
401011 | ticket already used | Enter travel. The ticket is single-use; obtain a new one. |
403001 | World does not exist, was deleted, does not belong to you, or does not belong to the current model | Query, credential exchange, enter travel, and list filtering. On delete, this code is returned only for cross-account, cross-workspace, or cross-model IDs; an already-nonexistent ID under the same account returns code=0, deleted=false. |
403002 | World is not ready or unavailable | Credential exchange, enter travel. Poll the build status until ready before operating. |
403003 | This endpoint allows the primary API Key only | World management, Travel list, artifacts, etc. Call with the primary API Key (starts with sk-). |
403004 | Input content failed the content-safety policy | Create World, send instruct. Adjust the text content and retry. |
403005 | Input image failed copyright or IP verification | Create World. Replace with a compliant image and retry. |
403007 | Feature or service quota not enabled | Create, credential exchange, enter travel. Confirm the corresponding model capability is enabled. |
403008 | Capacity configuration temporarily unavailable | Create, credential exchange, enter travel. Retry later or contact the service provider to scale up. |
404000 | Travel does not exist, does not belong to you, does not belong to the current model, or has no available artifacts | Travel status query, control, end, artifacts query. |
409000 | Request conflicts with the current resource state | Control endpoints such as pause, resume, end, and instruct; also returned when calling an endpoint a model does not support. |
429001 | Concurrency for the current spec is full | Enter travel. Retry later or raise the concurrency spec. |
429002 | Insufficient available capacity | Enter travel. Retry later. |
500000 | Internal system error | Unclassified exceptions; may also be returned when calling an unsupported endpoint (e.g., rewind on some models). |
500001 | Failed to allocate streaming resources | Enter travel. Retry later. |
Cross-model access does not reveal whether the resource exists: World endpoints return code=403001 and Travel endpoints return code=404000.
Travel failure errorCode
When querying Travel status or the Travel list, items with status=failed additionally carry the structured field errorCode and an English description errorMessage (see the corresponding API doc for the failure response structure). The errorMessage text for the same errorCode may differ between the query endpoints and the End Travel response; branch on errorCode, not on errorMessage.
| errorCode | errorMessage | Description |
|---|---|---|
TRAVEL_SESSION_INIT_FAILED | Failed to allocate inference resources. | The inference session failed to initialize when entering the travel, usually due to insufficient inference resources |
TRAVEL_NO_STREAM_AUTO_END | No video stream was received before timeout. | The client did not receive the stream before timeout; end the Travel by passing failCode in the End Travel request |
TRAVEL_STREAM_CREATE_FAILED | Failed to create the video stream. | Failed to create the streaming channel |
CONTENT_VIDEO_MODERATION_REJECTED | Something went wrong. | The experience picture was interrupted by the content-safety policy |
TRAVEL_RUNTIME_FAILED | The experience was interrupted by a runtime error. | Other runtime failures, or the server did not record a specific reason |
Any errorCode not listed can be treated as an unknown failure.