API Errors

Reference guide for error responses in the Attune API.

---

Overview

The Attune API uses a consistent error response format across most endpoints. This document explains the error structure and common error codes you may encounter.

---

Error Response Structure

API errors follow the next JSON structure:

{
  "message": "You do not have access to this namespace.",
  "errorCode": "namespace/unauthorized",
  "extraProps": { ... }
}

Field	Type	Description
message OR error	string	Human-readable error message
errorCode	string	Optional specific error code from the categories below
extraProps	object	Optional additional context (varies by error)

---

Error Categories

Quiz Errors

Error Code	Description
quiz/not_started	Quiz has not started yet; action requires started quiz.
quiz/started	Quiz is already started; action requires not started.
quiz/ended	Quiz has ended; action requires active quiz.
quiz/not_anonymous	Quiz is not anonymous; action requires anonymous quiz.
quiz/anonymous	Quiz is anonymous; action requires non-anonymous quiz.
quiz/not_found	Quiz with given ID does not exist.
quiz/not_inapp	Quiz is not in-app; action requires in-app quiz.
quiz/inapp	Quiz is in-app; action requires not in-app quiz.
quiz/updating_error	Error occurred while updating quiz data.

Namespace Errors

Error Code	Description
namespace/not_found	Namespace with given ID does not exist.
namespace/unauthorized	User is not authorized for this namespace.

General Errors

Error Code	Description
parameters/not_found	Required parameters are missing.
parameters/invalid	Parameters provided are invalid.
request/not_found	Requested resource using provided parameter could not be found with input parameter.

User Errors

Error Code	Description
users/not_found	User with given ID/email does not exist.
users/unauthorized	User is not authorized for this action.

CSV Errors

Error Code	Description
csv/invalid_header	CSV file has invalid or missing header.

---

Common HTTP Status Codes

Status Code	Description	Common Causes
400	Bad Request	Missing or invalid parameters, malformed request
401	Unauthorized	Authentication required or failed
403	Forbidden	User lacks permission for the action
404	Not Found	Resource does not exist
500	Internal Server Error	Unexpected server error

---

Common Error Scenarios

• Missing API key (x-api-key header not provided)
• Missing authentication token (x-token header not provided)
• Missing tenant identifier (x-tennant-id header not provided)
• Invalid or expired token
• Email not verified
• User not found or unauthorized
• Namespace not found or unauthorized
• Quiz not found, not started, ended, or wrong type for action
• Invalid parameters (IDs, query params, body fields)
• CSV upload with invalid header
• Forbidden actions (not admin, not namespace admin, not invited user, etc.)

---

Notes

• Some errors include additional context in the extraProps field
• Always check for error responses in your API integration