Errors
What our API returns when things go wrong, and what to do about it.
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
| Code | Meaning | What to do |
|---|---|---|
| 400 | Bad Request | Fix the request — the body or query params are malformed. Don't retry. |
| 401 | Unauthorized | Missing or invalid API key. Check the Authorization header. |
| 403 | Forbidden | Authenticated but not allowed. The key belongs to a different org or scope. |
| 404 | Not Found | The resource doesn't exist (or your key can't see it). Don't retry. |
| 409 | Conflict | The request collides with current state (e.g. duplicate name). |
| 422 | Unprocessable Entity | Validation failed. The message field lists the offending fields. |
| 429 | Too Many Requests | You're being rate limited. See Rate limits. |
| 5xx | Server Error | Our 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/estates \
-H "Authorization: Bearer $YNH_API_KEY" \
-H "Idempotency-Key: 8e1f0c7e-c2c2-4e3f-9a8a-37e0c5a0a3a2" \
-H "Content-Type: application/json" \
-d '{ "name": "Maple Heights" }'