Error Codes

The API uses standard HTTP status codes and structured error payloads to help clients diagnose failures.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

Code	Meaning
200	Request completed successfully.
201	Resource created successfully.
204	Request succeeded without a response body.
400	The request parameters are invalid.
401	Authentication is missing or invalid.
403	The credential lacks permission or the account is blocked.
404	The requested resource does not exist.
422	Validation failed.
429	The rate limit was exceeded.
500	An unexpected server error occurred.
503	The API is temporarily unavailable.

Error Code Reference

Code	Status	Description
UNAUTHORIZED	401	The API key or token is invalid, expired, or revoked.
FORBIDDEN	403	The key lacks the required scope, the account is inactive, or API access is disabled.
ACCOUNT_SUSPENDED	403	The company account is suspended and API operations are blocked.
NOT_FOUND	404	The resource does not exist or does not belong to your account.
VALIDATION_ERROR	422	The submitted request data failed validation.
HAS_ACTIVE_USERS	422	The company cannot be deleted while active users still exist.
SSO_DOMAIN_CLAIMED	422	The email domain is managed by another company through SSO.
INSUFFICIENT_SEATS	422	The reseller seat pool does not have enough available seats.
SEAT_LIMIT_REACHED	422	The company has reached its hard seat limit.
SEATS_IN_USE	422	The seat limit cannot be reduced below current usage.
RATE_LIMIT_EXCEEDED	429	The client exceeded the allowed request rate.

Handling Errors

try {
    const response = await fetch('/api/v1/reseller/companies', {
        method: 'POST',
        headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
    });

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

        if (error.error.code === 'RATE_LIMIT_EXCEEDED') {
            retryLater(error.error.details?.reset_at);
        }
    }
} catch (error) {
    reportNetworkFailure(error);
}