Errors

The API uses conventional HTTP response codes to indicate the success or failure of a request. All error responses follow a consistent Stripe-style envelope format.

HTTP status codes

Status code	Description
200 - OK	Everything worked as expected.
201 - Created	A new resource was successfully created.
204 - No Content	The request succeeded but there is no response body (e.g. deletes).
400 - Bad Request	The request was invalid — often a missing or malformed parameter.
401 - Unauthorized	No valid authentication credentials provided.
403 - Forbidden	The authenticated user doesn’t have access to the requested resource.
404 - Not Found	The requested resource doesn’t exist.
409 - Conflict	The request conflicts with the current state (e.g. duplicate email, already revoked key).
429 - Too Many Requests	Too many requests in a given time period. Slow down.
500 - Internal Server Error	Something went wrong on our end.

Error types

Every error response includes a type field that categorizes the error:

Type	Description
authentication_error	Invalid or missing authentication credentials.
authorization_error	Valid credentials, but insufficient permissions.
invalid_request_error	The request was malformed or contained invalid parameters.
not_found_error	The requested resource was not found.
conflict_error	The request conflicts with current state.
rate_limit_error	Too many requests — retry after the indicated period.
api_error	An unexpected internal error occurred.

Error codes

Common error codes returned by the API:

Code	Type	Description
invalid_credentials	authentication_error	Invalid email or password
invalid_refresh_token	authentication_error	Refresh token is invalid or expired
revoked_refresh_token	authentication_error	Refresh token has been revoked
email_taken	conflict_error	An account with that email already exists
reseller_store_not_found	not_found_error	Reseller store not found
reseller_store_access_forbidden	authorization_error	Not authorized to access this store
source_store_not_found	not_found_error	Source store not found
sync_job_not_found	not_found_error	Sync job not found
sync_job_not_retryable	invalid_request_error	Sync job cannot be retried in its current state
api_key_not_found	not_found_error	API key not found
api_key_already_revoked	conflict_error	API key was already revoked

Handling errors

We recommend writing code that handles errors by their type and code fields rather than relying on HTTP status codes alone.

const response = await fetch('https://api.example.com/v1/reseller_stores', {
  headers: { 'Authorization': 'Bearer sk_live_...' }
});

if (!response.ok) {
  const { error } = await response.json();
  
  switch (error.type) {
    case 'authentication_error':
      // Re-authenticate or refresh token
      break;
    case 'not_found_error':
      // Resource doesn't exist
      break;
    case 'rate_limit_error':
      // Back off and retry
      break;
    default:
      console.error(`API error: ${error.code} — ${error.message}`);
  }
}