Skip to content

API Error Codes and Quotas ​

Rate limits ​

V2 REST requests and Admin MCP tool calls share organization-level rate limits and daily quotas. Switching keys, members or transports within the organization uses the same allowance. Operations have different rate and accounting rules. MCP initialization, ping and tool discovery do not consume business quota.

Send {} to POST /api/v2/rpc/usage/get, or call the MCP tool usage_get, to inspect usage, reservations, remaining quota and reset times. REST returns HTTP 429 for rate or quota limits. Check data.error.code. For rate_limited, wait for the returned Retry-After (seconds) or retry_after_ms. For quota_exceeded, check remaining quota and reset time. Retry writes with the original parameters and idempotency key.

For the default read and write rates and daily quotas by edition, see Admin MCP and V2 REST limits.

Top-level code (general) ​

  • 0: success
  • 400: invalid parameters or business error
  • 401: invalid API key (auth failed)
  • 403: credential type, authorization level or resource access is insufficient. See permission troubleshooting
  • 404: resource not found or no permission
  • HTTP 429: rate or quota limit. The V2 usage guard returns a string error code in the response body.
  • 502: upstream service unavailable

Business error_code ​

When business errors occur, upstream may return error_code. The API passes it through to top-level error_code (along with top-level code and message).

Note: if upstream returns a non-2xx response that cannot be parsed, you may only see HTTP-layer errors such as 404/502, and error_code may be absent.

Module error codes (100300 ~ 100329):

error_codemessageDescription
100300System errorSystem error (unclassified internal exception).
100301Invalid request parametersInvalid request parameters (missing required fields, wrong type, or illegal values).
100302Unsupported versionUnsupported version (version cannot be recognized).
100303Record not foundRecord not found (record_id / record_url cannot locate a record).
100304Form not foundForm not found (tpl_id cannot locate a form).
100305Unsupported output formatUnsupported output format (format is invalid).
100306Form not assigned to this codeThe QR code is not associated with this form.
100307Duplicate submission not allowed for this fieldDuplicate submission not allowed (uniqueness check failed).
100308Required field is emptyRequired field is empty.
100309Field validation failedField validation failed (format/content invalid).
100310Submitted resource has expiredDependent resource has expired.
100311User submission limit reachedPer-user submission limit reached.
100312Form submission limit reachedForm submission limit reached.
100313Submission not allowed at current timeSubmission is not allowed at current time.
100314Submission not allowed in current code stateSubmission is not allowed in current QR code state.
100315API key invalid or disabledAPI key is invalid or disabled.
100316API key org mismatchAPI key organization does not match request.
100317No codes found in the selected categoryNo available QR codes in selected category.
100318Too many codes found in the selected categoryToo many QR codes matched (over system limit).
100319Certificate verification failedGeneric certificate verification failure.
100320Invalid certificate codeInvalid certificate code or target record not found.
100321Certificate verification is not enabledVerification is not enabled for the form/certificate.
100322Certificate record is not approved for verificationCertificate record is not approved yet.
100323Certificate does not match the requested scopeCertificate does not match tpl_id / code_id scope.
100324Certificate cannot be verified in current statusCertificate cannot be verified in current status, or flow ended.
100325Invalid verification actionUnsupported verification action or form configuration.
100326Invalid target certificate statusInvalid target status, missing status, or no next status.
100327Invalid verification authorization codeVerification authorization code invalid or expired.
100328No permission to verify this certificateCaller has no permission to verify this certificate.
100329Identity information required before verificationIdentity information must be completed before verification.