Errors
Branch on error_code. “Execution” tells whether the response carries an execution: if it does, an execution record exists and a retry needs a new invocation_id (except for unknown; see Retries).
| HTTP | error_code |
Execution | Meaning | Handling |
|---|---|---|---|---|
| 400 | COMMON.INVALID_INPUT |
no | Malformed JSON, unknown field, or trailing data | Fix the request |
| 401 | AUTH.UNAUTHORIZED |
no | Missing or invalid credential | Check the credential |
| 403 | AUTH.FORBIDDEN |
no | Scope missing | Request the scope |
| 404 | COMMON.NOT_FOUND |
no | Unknown route or resource | Check the path or id |
| 409 | EXECUTION.DUPLICATE_INVOCATION |
yes (existing) | The invocation_id was already executed |
Read the attached execution; do not bill again |
| 410 | <CAPABILITY>.RESULT_EXPIRED |
yes | The provider reported the result expired | Treat as failed |
| 413 | COMMON.REQUEST_TOO_LARGE |
no | Body over 64 KiB | Send less |
| 415 | COMMON.INVALID_INPUT |
no | Content type is not JSON | Send Content-Type: application/json |
| 422 | COMMON.VALIDATION_FAILED |
no | Field validation, unknown provider, unsupported optional field | Fix per message and the reference |
| 422 | <CAPABILITY>.INPUT_REJECTED |
yes | The provider rejected the input | Fix the input; call with a new id |
| 429 | COMMON.RATE_LIMITED |
no | Local concurrency limit; nothing was started | Retry later with the same id |
| 502 | EXECUTION.OUTCOME_UNKNOWN |
yes | Outcome unknown | Do not retry automatically; reconcile |
| 502 | PROVIDER.INVALID_RESPONSE |
yes | Unusable provider response | Treat as failed; may retry with a new id |
| 502 | PROVIDER.RESULT_TOO_LARGE |
yes | Result over the service limit | Narrow the query |
| 503 | SERVICES.RECORD_UNAVAILABLE |
no | Could not record; nothing was started | Retry later with the same id |
| 503 | SERVICES.PROVIDER_DISABLED |
no | Provider not accepting new work | Use another provider or retry later |
| 503 | PROVIDER.CONFIGURATION_ERROR |
yes | Provider credentials or account invalid | Contact the ZGI platform team |
| 503 | PROVIDER.RATE_LIMITED |
yes | Provider rate limit; Retry-After when supplied |
Back off per Retry-After; retry with a new id |
| 503 | PROVIDER.UNAVAILABLE |
yes | Provider unreachable or failed before completing | Back off; retry with a new id |
| 503 | COMMON.TIMEOUT |
yes | Timed out before the request was sent | Back off; retry with a new id |
<CAPABILITY> is the upper-cased capability id, for example PUBLIC_HOLIDAY.