Error codes

Every error is a ProblemDetails (RFC 7807): title, status, detail, traceId; 422 adds errors.

ProblemDetails

{
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient_scope: cần gis.parcels.view",
  "traceId": "req_b9a0…"
}

Code	Cause	Fix
`400 invalid_request`	A required parameter is missing (e.g. token request without client_secret).	Read the detail field.
`400 invalid_grant`	Code is wrong / expired (60 seconds) / already used, or redirect_uri does not match.	Have the farm install again for a new code; redeem it immediately.
`401 invalid_client`	Wrong App ID / App Secret, an old secret past its 24 hours, or the app is suspended.	Check the secret in App settings › App Secret.
`401 token_revoked`	The farm removed the app / changed scopes, or the app was deleted or suspended — old tokens die immediately.	Request a new token.
`401`	Wrong, expired or revoked key / token.	Recreate it or Generate Access Token.
`403 access_denied`	The farm has not installed the app (or removed it).	Send the install link.
`403 insufficient_scope`	The token lacks the scope for this operation.	Add it in Use cases; the farm re-consents.
`403 workspace.developer_sandbox_outbound_blocked`	Developer workspaces cannot send anything outside (Zalo OA, email, farm mailbox, public camera).	Expected — use a real farm if needed.
`404`	No such data, or it belongs to another farm.	Check the id.
`409`	Duplicate / wrong state (e.g. inviting the same member twice, reporting an app twice in 7 days).	Read detail.
`422`	Invalid request body — the errors field lists each problem.	snake_case JSON; send [] for empty arrays.
`429`	Over 600 calls/minute (app × farm / key) or 10/minute/IP for /oauth/token.	Wait Retry-After seconds.
`5xx`	NextFarm server error.	Retry with backoff; send the traceId (X-Correlation-ID) to support.

Debug quickly: API Explorer · Token Debugger · API Logs of your app.