title: Error Handling

description: Handle API errors gracefully in your Wontopos integration.

Error Handling

Wontopos uses standard HTTP status codes and returns structured JSON error objects for all failures.

Error response format

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 60 seconds.",
    "status": 429,
    "request_id": "req_abc123"
  }
}

Common errors

Code	Status	Description	Resolution
`authentication_failed`	401	Invalid or missing API key	Check your API key
`insufficient_scope`	403	Key lacks required permission	Add the required scope
`not_found`	404	Resource does not exist	Verify the resource ID
`invalid_parameter`	400	Invalid request parameter	Check request body/params
`rate_limit_exceeded`	429	Too many requests	Wait and retry with backoff
`internal_error`	500	Server error	Retry or contact support

Retry strategy

Retry on 429 and 5xx responses with exponential backoff:

Check the status code

Only retry on `429`, `500`, `502`, `503`, and `504`.

Read Retry-After header

If present, wait the specified number of seconds before retrying.

Exponential backoff

If no `Retry-After` header, wait `2^attempt` seconds (1s, 2s, 4s, 8s...).

Max retries

Stop after 3-5 attempts and surface the error.

Code example

import { WontoposError, RateLimitError } from "@wontopos/sdk";

try {
  const result = await client.marketplace.get("api_abc123");
} catch (err) {
  if (err instanceof RateLimitError) {
    // Wait and retry
    await sleep(err.retryAfter * 1000);
  } else if (err instanceof WontoposError) {
    console.error(`[${err.code}] ${err.message} (request: ${err.requestId})`);
  }
}

SDK retries

The official SDKs handle retries automatically. Manual retry logic is only needed for raw HTTP clients.

Idempotency

For POST requests, include an Idempotency-Key header to safely retry without duplicating operations:

curl -X POST https://api.wontopos.com/v1/subscriptions 
  -H "Authorization: Bearer $WONTOPOS_API_KEY" 
  -H "Idempotency-Key: unique-request-id-123" 
  -H "Content-Type: application/json" 
  -d '{"api_id": "api_abc123", "plan_id": "plan_pro"}'