Errors and version compatibility

Application error codes

All errors below return HTTP 200:

`data.error.code`	Meaning	Recommended action
`INVALID_REQUEST`	Invalid JSON, headers, Content-Type, method, path, or field format	Correct the request before retrying
`INVALID_API_KEY`	API Key is missing, malformed, invalid, or revoked	Use an active Key; do not blindly retry the original request
`FORBIDDEN`	The current account is not allowed to perform the operation	Confirm account permissions before retrying
`PROJECT_NOT_FOUND`	The Project ID is invalid or unavailable to the current account	Use a valid Project ID returned by the project list
`APP_NOT_FOUND`	The App ID is invalid or unavailable to the current account	Confirm the App ID and availability with the publisher
`APP_INPUT_INVALID`	An `inputJson` key, type, required value, or media URL violates the App contract	Correct the input before retrying
`INSUFFICIENT_BALANCE`	The wallet for the `projectId` project has insufficient balance	Add funds to the wallet for that project, then resubmit
`RATE_LIMITED`	The account-level rate limit was exceeded	Wait for `Retry-After`; creation calls must still prevent duplicate submissions
`SERVICE_UNAVAILABLE`	OpenAPI, rate limiting, or execution services are temporarily unavailable	Delay with backoff; retrying creation may create duplicate resources
`RUN_NOT_FOUND`	The Run ID is invalid or unavailable to the current account	Check the Run ID and account
`INTERNAL_ERROR`	An unexpected server error occurred or a frozen result is temporarily unreadable	Retry after a delay and retain the requestId; contact support if it persists

When listing published Apps, a missing projectId or an invalid pageNo or pageSize type or range returns INVALID_REQUEST. An invalid Project ID, or a project the current account cannot edit, returns PROJECT_NOT_FOUND.

Error-handling recommendations:

Follow Retry-After for RATE_LIMITED.
Use exponential backoff with random jitter for SERVICE_UNAVAILABLE, INTERNAL_ERROR, and network timeouts.
Creation APIs have no idempotency parameter. Do not blindly retry when the network result is unknown.
Do not retry parameter, authentication, permission, or balance errors without a limit.
When contacting support, provide the request time, API path, X-Request-Id, and data.error.code, but never the complete API Key.

Integration checklist

API Keys are stored only in a server-side secret store and never appear in frontend code or logs.
The system does not select a wallet based on the API Key; the project used to create a Run has the intended ownership.
The client gets the App ID from the project's App list, then reads the current input contract from App details.
Creation UI and network retry logic prevent duplicate submissions, and the client understands that another POST creates a new resource.
The client checks the top-level message for success; on failure it reads data.error.code, and on success it reads business results from data.
The client handles prices as decimal strings.
Media URLs use HTTPS, require no Cookie for the execution service to access, and do not point to private networks or temporary sign-in pages.
The client uses exponential backoff with jitter for network and retryable errors.
The client stops polling when the status becomes succeeded, partial_success, failed, or canceled.
Logs retain X-Request-Id while filtering Authorization headers and complete API Keys.

Version compatibility

The current version prefix is /openapi/v1. Clients must ignore unknown optional response fields added within v1. Existing fields will not change meaning or be removed. Breaking changes will use a new version prefix.