Skip to main content

​
Error format

When a request fails, the API returns a JSON error response with an HTTP status code: 
{
  "error": {
    "code": 422,
    "message": "Validation failed: amount must be greater than 0"
  }
}
FieldTypeDescription
codeintegerThe HTTP status code
messagestringA human-readable description of what went wrong

​
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 field 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.

​
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 IP address. When exceeded, you’ll receive a 429 response: 
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}
Check the Retry-After response header for the number of seconds to wait.

​
Handling errors in code

const response = await fetch("https://api.antonpayments.com/v1/payouts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  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.error.message);
      break;
    case 401:
      // Check API key
      console.error("Authentication failed");
      break;
    case 429:
      // Back off and retry
      const retryAfter = response.headers.get("Retry-After") || 30;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      // ... retry the request
      break;
    case 500:
    case 502:
    case 503:
      // Retry with backoff
      // ... implement 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.