Happily.ai Get an API key

Errors & status codes

When something goes wrong, the API returns a JSON error object. This guide covers the shape of errors, the HTTP status codes, and every error code you might see.

Error shape

Most errors follow this shape:

{
  "statusCode": 400,
  "error": true,
  "errorMsg": "email and question_id are required",
  "error_code": "VALIDATION_ERROR",
  "suggestion": "Provide at least one of the required parameters"
}
Field Notes
statusCode The status, also echoed in the JSON body.
error true on failure.
errorMsg / message Human-readable message. Some endpoints use message.
error_code Machine-readable code for branching logic. See the table below.
suggestion Optional hint for resolving the error.
errors Present on bulk validation failures (see below).

Bulk validation errors

Member import returns a per-field errors array so you can pinpoint bad rows:

{
  "error": true,
  "errorMsg": "Request validation failed",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    { "field": "members[0].email", "message": "Email format is invalid" },
    { "field": "members[1].timezone", "message": "Timezone must be between -12 and 14" }
  ]
}

HTTP status codes

Status Meaning
200 Success. For bulk endpoints, check per-item results inside the body.
400 Bad request. A required parameter is missing or invalid.
403 Forbidden. Missing/invalid API key, wrong stage, or access denied.
404 Not found. The resource (for example, a user) does not exist.
409 Conflict. For example, a member was already reviewed this cycle.
429 Too many requests. You hit the rate limit.
500 Server error. Something failed on our side.
503 A referenced email (sender or recipient) was not found in your company.
Note

The status is also included as statusCode in the response body. When in doubt, branch on both the HTTP status and error_code.

Error codes

Authentication & access

Code / message Status Fix
Invalid API Key. 403 Check the key value.
Invalid API Key by stage. 403 Match the key to the stage in the URL.
ACCESS_DENIED 403 The resource belongs to another company.
USER_NOT_FOUND 404 Verify the email exists in your company.
INVALID_PARAMETERS 400 Fix the query parameters (for example, context_limit 1–50).

Member import

Code Meaning
VALIDATION_ERROR One or more members failed validation. See errors.
EMAIL_ALREADY_EXISTS Email exists; use update_if_exists or skip_duplicates.
DUPLICATE_ACTION / DUPLICATE_SELF_ACTION The same member appears twice, or a pending import already covers them.
MANAGER_NOT_FOUND manager_email is not in the system or the same batch.
RATE_LIMIT_EXCEEDED More than 10 requests/minute, or more than 1,000 members in one request.
IMPORT_FAILED The import could not be written. Retry.

Performance boosts

Code Meaning
MISSING_EMPLOYEE_EMAIL / MISSING_REVIEWER_EMAIL / MISSING_REVIEW_DATE A required field is missing.
INVALID_INPUT An email is malformed.
EMPLOYEE_NOT_FOUND The employee or reviewer is not in your company.
SENDER_WRONG_COMPANY / RECEIVER_WRONG_COMPANY A person belongs to another company.
INVALID_BOSS_RELATIONSHIP The reviewer is not the employee's direct manager.
EMPLOYEE_REVIEW_COMPLETED The employee was already reviewed this cycle (409).
MISSING_GOAL_EXAMPLES / MISSING_CULTURE_EXAMPLES supporting_examples is required.
INVALID_GOAL_RATING / INVALID_CULTURE_RATING The rating is not one of the allowed values.
Important

Performance boosts are processed per item. A 200 response can still contain failed items. Always inspect each entry in the returned array for success or error.

Next steps