Error Handling

The Zaki-Pass API uses standard HTTP status codes. All error responses follow a consistent JSON format.

Error Response Format

All error responses include these fields:

`statusCode`	HTTP status code (400, 401, 403, 404, 409, 429)
`message`	Human-readable error description. Can be a string or array of validation errors.
`error`	Error type name (e.g., "Bad Request", "Not Found")

Error Code Reference

400Bad Request

The request was malformed or contained invalid parameters. Check the request body and query parameters.

json

{
  "statusCode": 400,
  "message": [
    "templateId must be a string",
    "email must be an email"
  ],
  "error": "Bad Request"
}

401Unauthorized

Authentication failed. The API key is invalid, expired, or missing. For JWT, the token may be expired or malformed.

json

{
  "statusCode": 401,
  "message": "API key has expired",
  "error": "Unauthorized"
}

403Forbidden

The authenticated user or API key does not have the required permissions (scopes) for this endpoint.

json

{
  "statusCode": 403,
  "message": "API key missing required scope(s): passes:write",
  "error": "Forbidden"
}

404Not Found

The requested resource was not found. Check the ID or path parameter.

json

{
  "statusCode": 404,
  "message": "Pass not found",
  "error": "Not Found"
}

409Conflict

The request conflicts with existing data. For example, a duplicate slug or email.

json

{
  "statusCode": 409,
  "message": "Organization slug already exists",
  "error": "Conflict"
}

429Too Many Requests

You have exceeded the rate limit (100 requests per minute). Wait and retry.

json

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}

Handling Errors in Code

Always check the response status code and handle errors gracefully:

javascript

const response = await fetch('https://api.zakipass.com/api/v1/passes/issue', {
  method: 'POST',
  headers: {
    'X-API-Key': 'zk_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ templateId: 'TEMPLATE_ID' }),
});

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

  switch (response.status) {
    case 400:
      console.error('Validation error:', error.message);
      break;
    case 401:
      console.error('Authentication failed — check your API key');
      break;
    case 403:
      console.error('Missing scope:', error.message);
      break;
    case 404:
      console.error('Resource not found:', error.message);
      break;
    case 429:
      const retryAfter = response.headers.get('Retry-After');
      console.error(`Rate limited. Retry after ${retryAfter}s`);
      break;
  }
  return;
}

const data = await response.json();