Errors & Rate Limits

All API errors are returned as JSON with a message field describing the problem. Validation errors include a missing_fields array naming the affected fields.

Error Body Shape

json

{
  "message": "A human-readable description of the error",
  "missing_fields": ["field_a", "field_b"]
}

missing_fields is only present for 400 validation failures on structured request parsers.

HTTP Status Codes

Status	Meaning	Example message
`400`	Bad request — invalid or missing data, constraint violation	`{"message": "Missing required fields", "missing_fields": [...]}`
`401`	Missing or invalid credentials	`{"message": "..."}`
`403`	Authenticated but insufficient permissions	`{"message": "Access Denied..."}`
`404`	Resource not found	`{"message": "..."}`
`409`	Duplicate / conflicting resource	`{"message": "..."}`
`428`	Precondition required	`{"message": "..."}`
`429`	Rate limit exceeded	`{"message": "Too many requests. Please try again later."}`
`498`	Invalid device credential	`{"message": "..."}`
`500`	Internal server error	`{"message": "An unexpected error occurred. Please try again later."}`
`501`	Not implemented	`{"message": "..."}`
`503`	Gateway timeout	`{"message": "..."}`

Rate Limits

Requests are rate-limited per client IP. When a limit is exceeded the API returns 429 with {"message": "Too many requests. Please try again later."}

Limit	Scope
`300` requests per minute	Per client IP, all endpoints (default)
`10` requests per second	Per client IP, all endpoints (default)
`4` sign-in attempts per minute	Per phone number on the sign-in endpoint

Recommended: implement exponential backoff on 429 responses and retry idempotently.

API Versions

The current default version is v1 (all base endpoints under /api). Additional versions (v2 and booklet) exist; versioned endpoint paths take precedence when used. Breaking changes are announced as part of the DidYouGo release notes.

Example Error Response

json

{
  "message": "Missing required fields",
  "missing_fields": ["organization_uuid"]
}