Errors and retries

Read error.code to decide what to do next. For a field validation error, look in error.fields.

HTTP status and code	Next step
401 app_key_required or app_key_invalid	Check X-App-Key, the API environment, and whether the key and app are active.
400 app_version_required	Add a nonempty X-App-Version header.
401 token_app_mismatch	Check that the token came from the same app identified by the AppKey.
401 token_not_valid	Check token expiry and follow the refresh flow. If refresh is rejected, obtain a new session.
400 invalid_request	Correct the fields listed in the response. For image effects, check that the image is attached and the effect still appears in the catalog.
503 effect_failed	The API could not apply the effect. If it persists, share the operation, timestamp, and error code with Backapp support. Keep tokens and provider credentials private.

For example, submitting an effect ID without an image returns HTTP 400 with error.code set to invalid_request and an image entry under error.fields.

If the connection drops during image processing, the provider may have completed the operation. Resending the request can start another provider call. Avoid automatic retries when the outcome is unknown. Proxy failures may have a different response format, so check the HTTP status before parsing the body.