Errors - HumDov Developer API

Every successful response is shaped {"data": ...} (plus "pagination" on list endpoints). Every error response is shaped the same way everywhere in the API:

{
  "error": {
    "code": "not_found",
    "message": "Member not found"
  }
}

code is a short, stable, machine-readable string — safe to branch your own error handling on. message is for humans and may change wording over time; don’t parse it.

Reading “not found”

A 404 not_found means either the record genuinely doesn’t exist, or it exists but belongs to a different organization than your API key. The API deliberately never distinguishes the two — returning a 403 instead would confirm to a caller that something exists at that id, even if they can’t see it. If you’re sure an id is right and still get not_found, double check it belongs to the same organization your key was created for.

Common error codes

HTTP status	`error.code`	Meaning
400	`invalid_json`	The request body isn’t valid JSON, or isn’t a JSON object
401	`missing_api_key` / `invalid_api_key` / `key_revoked` / `key_expired`	See Authentication
403	`missing_scope`	Your key doesn’t have the scope this endpoint requires
404	`not_found`	The record doesn’t exist, or isn’t yours — see above
405	`method_not_allowed`	That HTTP method isn’t supported on this endpoint
409	`already_exists`	A conflicting record already exists (e.g. duplicate email/phone, duplicate check-in)
422	`missing_fields`	A required field is missing from the request body
422	`invalid_field`	A field’s value failed validation (bad email, bad phone number, invalid choice, etc.)
422	`unsupported_field_type`	A form field type the v1 API doesn’t support yet (`file_upload`, `payment`)
429	`rate_limited`	Too many requests — see Rate limits
500	`internal_error`	Something went wrong on Humdov’s side. Safe to retry.

Some endpoints raise a few additional, endpoint-specific codes (e.g. form_not_published on form submission, plan_not_supported on attendance for orgs without that feature) — those are documented on the endpoint’s own reference page.

​Reading “not found”

​Common error codes

Reading “not found”

Common error codes