Errors
Zoneless uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error given the information provided (e.g., a required parameter was omitted, authentication failed, etc.). Codes in the 5xx range indicate an error with the Zoneless server.
All errors return a JSON object with an error key containing message and type fields. In production, a request_id is also included for tracing.
Attributes
message string A human-readable message providing more details about the error.
type enum The type of error returned.
api_errorCovers any other type of problem (e.g., a temporary problem with the server) and is uncommon.authentication_errorFailure to properly authenticate in the request.idempotency_errorThe idempotency key was reused on a request that is still processing, or was used with different parameters.invalid_request_errorThe request has invalid parameters or cannot be otherwise served.rate_limit_errorToo many requests hit the API too quickly.permission_deniedThe API key does not have permission to perform the requested action (e.g., a connected account accessing a platform-only endpoint).resource_missingThe requested resource does not exist.validation_errorA request body field failed schema validation.conflictThe request conflicts with another request or the current state of a resource (e.g., creating a duplicate resource).request_idnullable string A unique identifier for the request, useful for debugging. Only included in production environments.
{
"error": {
"message": "Account not found",
"type": "resource_missing",
"request_id": "req_z_abc123"
}
} HTTP Status Code Summary
200 - OK status Everything worked as expected.
400 - Bad Request status The request was unacceptable, often due to a missing or invalid parameter.
401 - Unauthorized status No valid API key provided.
403 - Forbidden status The API key doesn't have permissions to perform the request.
404 - Not Found status The requested resource doesn't exist.
409 - Conflict status The request conflicts with another request (perhaps due to using the same idempotency key, or creating a duplicate resource).
410 - Gone status The requested resource is no longer available (e.g., an account link that has already been used).
429 - Too Many Requests status Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Server Error status Something went wrong on the server.
Error Types
api_error type Covers any other type of problem (e.g., a temporary problem with the server) and is uncommon.
authentication_error type Failure to properly authenticate in the request. Check that you are providing a valid API key via the x-api-key header or Authorization: Bearer header.
idempotency_error type Occurs when an Idempotency-Key is reused on a request that is still processing, or was previously used with different parameters.
invalid_request_error type The request has invalid parameters, invalid JSON, or cannot be otherwise served.
permission_denied type The API key does not have permission to perform the requested action (e.g., a connected account accessing a platform-only endpoint).
rate_limit_error type Too many requests hit the API too quickly. The response includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
resource_missing type The requested resource does not exist. Check that the ID you provided is correct and that the resource belongs to your platform.
validation_error type A request body field failed schema validation. The message will include the field path and reason (e.g., email: Invalid email).
conflict type The request conflicts with another request or the current state of a resource (e.g., creating a duplicate resource).
Handling errors
The Zoneless Node.js SDK raises exceptions for API errors, letting you handle them with try/catch. The error object contains message, type, and statusCode properties.
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');
try {
const account = await zoneless.accounts.retrieve('acct_z_invalid');
} catch (error) {
console.log(error.statusCode); // 404
console.log(error.type); // "resource_missing"
console.log(error.message); // "Account not found"
}