Skip to main content

​
Error format

When a request fails, the API returns a JSON error response with an HTTP status code: 
{
  "error": {
    "message": "Validation failed: amount must be greater than 0",
    "code": "validation_error",
    "details": {
      "field": "amount",
      "reason": "must be greater than 0"
    }
  }
}
FieldTypeDescription
messagestringA human-readable description of what went wrong
codestringA machine-readable error code (e.g., validation_error, insufficient_balance, rate_limit_exceeded)
detailsobjectAdditional context about the error. Present for validation errors and other cases where field-level detail is available.

​
HTTP status codes

​
Success codes

CodeMeaning
200 OKRequest succeeded
201 CreatedResource created successfully
204 No ContentRequest succeeded, no body returned (e.g., delete)

​
Client error codes

CodeMeaningWhat to do
400 Bad RequestInvalid request body or parametersCheck the message and details fields for specifics. Fix the request and retry.
401 UnauthorizedMissing or invalid API keyCheck your Authorization header. Ensure the key isn’t revoked.
403 ForbiddenValid key but insufficient permissionsYour key doesn’t have access to this resource or action.
404 Not FoundResource doesn’t existCheck the ID in your URL. The resource may have been deleted.
409 ConflictState conflict (e.g., cancelling a completed payout)The resource can’t transition to the requested state. Check current status.
422 Unprocessable EntityValidation errorThe request body is syntactically valid JSON but semantically wrong.
429 Too Many RequestsRate limit exceededBack off and retry after the Retry-After header value. See Rate limiting below.

​
Server error codes

CodeMeaningWhat to do
500 Internal Server ErrorSomething went wrong on our endRetry with exponential backoff. If persistent, contact support.
502 Bad GatewayUpstream service unavailableRetry in a few seconds.
503 Service UnavailableService temporarily unavailableRetry with backoff. Check status page.

​
Rate limiting

The API enforces rate limits per merchant at 1,000 requests per minute. Every response includes rate limit headers so you can monitor your usage:
HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed per window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the rate limit window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)
When you exceed the limit, the API returns a 429 response: 
{
  "error": {
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "code": "rate_limit_exceeded"
  }
}
Use the Retry-After header to determine how long to wait, or use the X-RateLimit-Reset timestamp to calculate the delay.

​
Handling errors in code

const response = await fetch("https://api.antonpayments.dev/v1/payouts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify(payoutData),
});

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

  switch (response.status) {
    case 400:
    case 422:
      // Fix the request - don't retry
      console.error("Validation error:", error.message);
      if (error.details) {
        console.error("Details:", error.details);
      }
      break;
    case 401:
      // Check API key
      console.error("Authentication failed");
      break;
    case 429: {
      // Back off and retry
      const retryAfter = parseInt(response.headers.get("Retry-After") || "30", 10);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      // ... retry the request
      break;
    }
    case 500:
    case 502:
    case 503:
      // Retry with exponential backoff
      break;
  }
}
Never retry 4xx errors (except 429). They indicate a problem with your request that won’t be fixed by retrying. Only retry 5xx errors and rate limit (429) responses.