MyazaTrust

Errors
Build with

The API uses conventional HTTP status codes and returns a JSON body with an error field (and sometimes a message) on failure.

json
{ "error": "business_not_approved", "message": "Your business must be approved …" }

Status codes
Build with

StatusMeaningTypical causes
200OKSuccessful GET/upload.
202AcceptedVerification queued (see create verification).
400Bad requestInvalid body, bad/missing field, unsupported file type, file too large.
401UnauthorizedMissing Authorization header, or invalid/revoked API key.
403ForbiddenProduction key without an approved business, a publishable key on a secret-only endpoint (secret_key_required), or a requestId owned by another org.
404Not foundVerification ID does not exist (or isn't yours).
429Too many requestsRate limit exceeded.
500Server errorE.g. pricing not configured for the requested country/ID type.

Common error bodies
Build with

errorStatusMeaning
Missing or invalid Authorization header401No Bearer token sent.
Invalid API key401Key is unknown or revoked.
Invalid request body400Verify payload failed validation; see message for details.
Forbidden403The requestId belongs to a different organization.
business_not_approved403Production access requires an approved business.
secret_key_required403A publishable (pk_) key was used on a secret-only endpoint (full result or media). Use a secret (sk_) key from your backend — see authentication.
environment_mismatch403The key's environment doesn't match the server it was sent to (e.g. a pk_live_ key against the sandbox host). Use the base URL for the key's environment.
Verification not found404Unknown verification ID.
File too large (max 25MB)400Upload exceeded the size cap.
Too many requests, please try again later.429Slow down; see rate limits.
pricing_not_configured500No price set for that country/ID type — contact Myaza.

Asynchronous failures
Build with

A 202 Accepted from create verification only means the request was queued. The verification can still finish as failed, not_found, or error. Those are not HTTP errors — read them from GET /status/:id or the verification.* webhooks.

Each non-success outcome carries a human-readable reason plus a stable reasonCode you can branch on (e.g. document_expired, selfie_mismatch, identity_not_found). The full catalog is in failure reason codes.

Health check
Build with

code
GET /api/kyc/health

A public, unauthenticated endpoint for uptime monitoring.

json
{ "status": "ok" }

Handling errors well
Build with

  • Treat 5xx and 429 as retryable — back off and retry with the same metadata.requestId so you don't create duplicates.
  • Treat 4xx (except 429) as non-retryable — fix the request; retrying unchanged will fail again.
  • Always read the error/message fields; don't rely on status code alone.