YourNextHome

Errors

The YourNextHome API returns conventional HTTP status codes. The body of an error response is a JSON object with statusCode, message, and error fields.

{
  "statusCode": 404,
  "message": "Estate not found",
  "error": "Not Found"
}

Status codes you should handle

CodeMeaningWhat to do
400Bad RequestThe body or query params are malformed. Fix the request; don't retry.
401UnauthorizedMissing or invalid API key. Check the Authorization header.
403ForbiddenAuthenticated but not allowed. The key belongs to a different org or scope.
404Not FoundThe resource doesn't exist (or your key can't see it). Don't retry.
409ConflictThe request collides with current state (e.g. duplicate name).
422Unprocessable EntityValidation failed. The message field lists the offending fields.
429Too Many RequestsYou're being rate limited. See Rate limits.
5xxServer ErrorOur problem. Retry with exponential backoff; if it persists, contact us.

Idempotency

Endpoints that create resources accept an Idempotency-Key header. Pass a unique key per logical operation (e.g. a UUID generated by your client) so safely retrying after network errors does not produce duplicate records.

curl https://api.yournexthome.app/api/v1/estate \
  -H "Authorization: Bearer $YNH_API_KEY" \
  -H "Idempotency-Key: 8e1f0c7e-c2c2-4e3f-9a8a-37e0c5a0a3a2" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Maple Heights" }'