Skip to main content

Error Codes

All API errors return a consistent JSON envelope:
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has 0 credits remaining. Top up at https://app.zupertry.com/billing."
  }
}
Use error.code for programmatic handling and error.message for display.

Authentication errors

CodeHTTPWhenFix
invalid_api_key401API key not found in the systemCheck the key is correct and hasn’t been deleted
api_key_revoked401API key was manually revokedGenerate a new key in the console
api_key_disabled401API key is disabled (not revoked)Re-enable the key in the console under API Keys
invalid_token401Firebase ID token is invalid or expiredRe-authenticate and obtain a fresh ID token
unauthorized401Request is missing authentication entirelyAdd Authorization: Bearer <key> header
email_not_verified403Firebase user’s email is not verifiedComplete email verification first
forbidden403Authenticated but not authorised for this resourceCheck you’re using the right org/workspace

Account errors

CodeHTTPWhenFix
account_suspended403The organisation is suspendedContact support at support@zupertry.com
onboarding_already_completed409Tried to run onboarding again on an existing orgRedirect to /dashboard instead
api_key_limit_reached429Organisation has 10 API keys (the maximum)Revoke unused keys before creating a new one
workspace_limit_reached429Organisation has 25 workspaces (the maximum)Delete unused workspaces first

Credit and billing errors

CodeHTTPWhenFix
insufficient_credits402Not enough credits to process the jobTop up credits at /billing
no_payment_method422Tried to enable auto-reload without a saved payment methodAdd a card first at /billing
payment_provider_error502Razorpay returned an errorRetry after a moment; contact support if persistent

Job errors

CodeHTTPWhenFix
job_not_found404Job ID does not exist or belongs to a different orgCheck the job ID
output_not_ready400Job exists but is still processingPoll again or wait for webhook
job_not_cancellable409Job is already completed, failed, or cancelledNothing to cancel

Resource errors

CodeHTTPWhenFix
workspace_not_found404Workspace ID invalid or belongs to a different orgCheck the workspace ID
key_not_found404API key ID not foundCheck the key ID
member_not_found404User UID not found in the orgCheck the member list
invite_not_found404Invite ID not foundThe invite may have already been accepted or expired
invite_expired410Invite link has expired (7-day TTL)Request a new invite from your admin
endpoint_not_found404API route doesn’t existCheck the API reference for the correct path

Validation errors

CodeHTTPWhenFix
validation_error422Request body is missing required fields or has invalid valuesSee error.message for the specific field
invalid_mime_type400Image MIME type is not supportedUse image/jpeg, image/png, or image/webp
file_too_large400Uploaded file exceeds 10 MBResize or compress the image before uploading

Rate limiting

CodeHTTPWhenFix
rate_limit_exceeded429Too many API requests in the current windowWait and retry. Check Retry-After header if present. Contact sales for a higher limit

Internal errors

CodeHTTPWhenFix
internal_error500Unexpected server-side errorRetry after a moment. If persistent, contact support with the job ID and timestamp

Handling errors in code

async function submitTryOn(modelUrl, garmentUrl) {
  const res = await fetch('https://app.zupertry.com/v1/tryon', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ZUPERTRY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model_image_url: modelUrl,
      garment_image_url: garmentUrl,
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();

    switch (error.code) {
      case 'insufficient_credits':
        throw new Error('Please top up your credits at app.zupertry.com/billing');
      case 'rate_limit_exceeded':
        // Retry after 60s
        await new Promise((r) => setTimeout(r, 60_000));
        return submitTryOn(modelUrl, garmentUrl);
      case 'invalid_api_key':
      case 'api_key_revoked':
        throw new Error('API key is invalid. Check your ZUPERTRY_API_KEY environment variable.');
      default:
        throw new Error(`Zupertry error [${error.code}]: ${error.message}`);
    }
  }

  return res.json();
}