Errors

The ION Guard API uses standard HTTP status codes and returns error messages in a consistent JSON format.

Error response format

Simple error

{
  "message": "Invalid credentials."
}

Validation error (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["O campo email é obrigatório."],
    "password": ["A senha deve ter pelo menos 8 caracteres."]
  }
}

The message field provides a readable summary (usually the first validation message) and the errors field is an object where each key is the field name and the value is an array with all error messages for that field. Always base error display on the errors object, not just on message.

Status codes

Code	Meaning	When it occurs
200	OK	Successful request
201	Created	Resource created successfully
204	No Content	Successful operation with no response body
401	Unauthorized	Token missing, invalid, or expired
403	Forbidden	Authenticated user without permission for the action
404	Not Found	Resource not found
422	Unprocessable Entity	Validation error in the submitted data
429	Too Many Requests	Rate limit exceeded — see Rate Limiting
500	Server Error	Internal server error

Recommended handling

401 — Expired token

When you receive a 401, try refreshing the token via refresh. If the refresh also fails, redirect to login.

Request → 401 → POST /auth/refresh → New token → Retry request
               → 401 on refresh → Redirect to login

422 — Validation errors

Iterate over the errors object to display specific messages per field:

const response = await fetch('/api/v1/sites', { method: 'POST', body, headers });

if (response.status === 422) {
  const { errors } = await response.json();
  // errors.name → ["The name field is required."]
  // errors.timezone → ["The selected timezone is invalid."]
}

429 — Rate limit

Wait the time indicated in the Retry-After header and retry the request:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  // Retry request
}

500 — Server error

500 errors indicate a problem on the server. Do not retry the request immediately. If it persists, check the server logs or contact support.