Error Handling

The VisitNote API uses standard HTTP status codes and a consistent error response format. All error responses include a descriptive message to help you diagnose issues.

Error Response Format

{
  "status": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

The errors field is present only on 422 Validation Error responses and contains field-specific error messages.

HTTP Status Codes

Status	Meaning	What to Do
`200`	OK	Request succeeded. Parse the `data` field.
`401`	Unauthorized	Token is missing, invalid, or expired. Re-authenticate.
`403`	Forbidden	Token is valid but lacks permission for this resource.
`404`	Not Found	Resource does not exist. Verify the UUID/ID.
`409`	Conflict	Duplicate resource or conflicting state (e.g., already joined org).
`413`	Payload Too Large	File upload exceeds size limit. Reduce file size.
`422`	Validation Error	Request body failed validation. Check the `errors` field.
`429`	Rate Limited	Too many requests. Wait and retry with exponential backoff.
`500`	Server Error	Internal error. Retry after a short delay. If persistent, contact support.

Handling 401 Unauthorized

When you receive a 401 response, your JWT token has expired or is invalid. Recommended handling:

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${token}` },
});

if (response.status === 401) {
  // Token expired — clear stored token and re-authenticate
  clearStoredToken();
  const newToken = await signIn(email, password);
  // Retry the original request with the new token
}

Handling Validation Errors (422)

Validation errors include per-field error messages. Display them to the user or use them to fix the request:

const response = await fetch(url, { method: 'POST', body, headers });
const data = await response.json();

if (response.status === 422 && data.errors) {
  // data.errors = { "email": ["Email already taken"], "password": [...] }
  for (const [field, messages] of Object.entries(data.errors)) {
    console.error(`${field}: ${messages.join(', ')}`);
  }
}

Retry Strategy

For transient errors (429, 500, network timeouts), use exponential backoff:

1st retry: wait 1 second
2nd retry: wait 2 seconds
3rd retry: wait 4 seconds
Maximum 3 retries before failing

Do not retry 401, 403, 404, or 422 errors — these require fixing the request itself.

Timeouts

The API has a 30-second response timeout for most endpoints. File upload endpoints (audio upload, AI processing) have a 120-second timeout. Set your HTTP client timeout accordingly.