Errors and retries | AppForges Developer Center

Error structure

Gateway errors contain a nested error with numeric code, string status, and diagnostic details. HTTP status, server error code and ErrorInfo reason are different fields. Business endpoint details depend on the actual response.

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "Missing credential",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "MISSING_CREDENTIAL",
      "domain": "iam.appforges.com"
    }]
  }
}

HTTP	Verified reason	Action
401	`MISSING_CREDENTIAL`	Supply valid credentials
401	`OAUTH_TOKEN_INVALID`	Check user token, issuer and expiry
404	`user_mismatch`	Check resource path and caller identity
429	`RATE_LIMIT_EXCEEDED`	Honor `Retry-After`

Read diagnostic IDs from X-Request-Id / X-Trace-Id. SDK errors preserve status, reason, request ID and retry advice. Avoid message-based branching and logging credentials or full user responses.

Retry boundaries

Official SDKs default to two additional retries. For 429, Retry-After takes precedence; SDKs also handle retryable network/server failures. Fix requests or authorization for 401/403/404. Cancellation or context ends waiting. The quickstart disables retries to observe one initial call.

Retry a write only if the endpoint supports idempotency and all attempts reuse one X-Idempotency-Key. Use a different key for a different business operation.

X-Idempotency-Key: example-stable-operation-key

A key does not make arbitrary writes idempotent. Deduplication storage, retention and conflicting-payload handling are endpoint-specific; there is no universal 24-hour gateway response-cache guarantee. Do not wrap the SDK in an unbounded retry loop.

Rate information

Read X-RateLimit-Limit-Short, Remaining-Short, Reset-Short and the Long equivalents. Reset is a Unix timestamp. Limits come from actual responses and headers are normally also present on 429. Honor the delay and bound concurrency and retries.

See SDKs and versioning.