Common Error Definitions¶
The following errors apply to general authentication and request handling for the External API. For endpoint-specific business errors, see each endpoint page.
| HTTP Status | errorCode | Trigger Conditions and Handling |
|---|---|---|
| 400 | ft.InvalidNonce | Missing nonce or nonce reuse. Use a new nonce for each retry and re-sign the request. |
| 400 | ft.MissingAuthHeaderInfo | Missing Access Key, signature, or timestamp. Check the signature request headers. |
| 400 | ft.IllegalTimestamp | The timestamp exceeds the allowed configured deviation. Synchronize the client clock, use Unix seconds, and re-sign the request. |
| 403 | ft.CrosssValidateFailed | Signature mismatch. Check the signature version, original request path, query string, and string to sign. |
| 403 | ft.Forbidden | The signing account has insufficient permissions. Check the read and write permissions required by the endpoint. |
| 404 | ft.InvalidAccessKey | Invalid Access Key. Check the site being called and the platform account configuration. |
| 404 | ft.NotFoundAkSkCfg | The service could not find the External API signing account configuration. Contact the service administrator. |
| 406 | ft.ParameterValidationFailed | A parameter violates the declared field constraints. Correct the request based on the field and rule in message. |
| 400 | ft.RequestJsonFormatError | JSON syntax error. Use content.reason, line, and column to locate it. |
| 429 | ft.ApiMultiEntryRateLimited | The endpoint hit a configured rate limiting group. Back off according to Retry-After (if present) and re-sign with a new nonce. |
| 503 | ft.ApiMultiEntryRateLimitUnavailable | The applicable rate limiting service is temporarily unavailable. Retry later. |
| 500 | ft.InternalServerError | Internal error. Save the traceId in the response for troubleshooting. |
message may vary by language or field context. Clients can branch on the HTTP status and errorCode.