Errors

Every Ur Next Door API error code, its HTTP status, what causes it and what to do, plus how to read validation errors and which requests are safe to retry.

View as Markdown

Every error answers JSON in the same shape, whatever the Accept header:

JSON

{
  "ok": false,
  "error": "title and body are required",
  "code": "validation_failed",
  "errors": { "body": "Body is required." },
  "request_id": "a1b2c3d4e5f60718"
}

Field	Meaning
`ok`	Always `false` on an error.
`error`	A human readable message. Show it to people; do not parse it.
`code`	A stable machine code. Branch on this.
`errors`	Only on validation failures: one message per field name.
`request_id`	The same as the `X-Request-Id` header. Quote it when you contact support.

Error codes

Status	Code	Cause	What to do
400	`invalid_json`	The body is not a JSON object (an array, a string, or broken JSON).	Send a JSON object.
400	`invalid_idempotency_key`	The `Idempotency-Key` header is not 1 to 64 letters, digits or `. _ : -`.	Use a UUID.
401	`missing_api_key`	No key header.	Send `Authorization: Bearer ...` or `X-API-Key`.
401	`invalid_api_key`	The key is unknown, mistyped, revoked or expired, or the account is not active.	Check the key or create a new one. Do not retry in a loop.
403	`insufficient_scope`	The key lacks the scope this endpoint needs.	Create a key with that scope.
403	`forbidden`	You may not do this, for example you are not an editor of that community.	Choose another community, or ask its admins.
404	`not_found`	Unknown route or item, or it is not yours, or it is no longer scheduled.	Check the path, type and id.
409	`conflict`	It clashes with the current state: a community with that name exists, or the item is no longer scheduled.	Change the name, or refresh your list.
409	`idempotency_in_progress`	A request with the same `Idempotency-Key` is still running.	Wait a moment and retry with the same key.
413	`payload_too_large`	The body is over its limit, or the image is over 8 MB.	Shrink it. See limits.
415	`unsupported_media_type`	Wrong `Content-Type`, or a file type that is not allowed.	Send `application/json` (or multipart for media), and PNG, JPEG, GIF or WebP.
421	`wrong_host`	You called a community subdomain.	Use `https://urnextdoor.com/api/v1`.
422	`validation_failed`	One or more fields are missing or wrong.	Fix the fields named in `errors`.
422	`idempotency_key_reused`	The same `Idempotency-Key` was sent with a different request.	Use a new key for a new request.
429	`rate_limited`	More than 60 requests a minute from you, or too many failed key checks from your address.	Wait `Retry-After` seconds.
429	`quota_exceeded`	Today's quota for this action is used up.	Wait for 00:00 UTC (see `Retry-After`).
500	`server_error`	Something went wrong on our side.	Retry with the same `Idempotency-Key`. If it persists, contact support with the `request_id`.
503	`api_disabled`	The API is switched off.	Try again later.

Treat unknown codes by their HTTP status: new codes may be added over time.

Validation errors

A 422 validation_failed names each field that needs fixing:

JSON

{
  "ok": false,
  "error": "Choose a time at least 5 minutes from now.",
  "code": "validation_failed",
  "errors": { "scheduled_at": "Choose a time at least 5 minutes from now." },
  "request_id": "a1b2c3d4e5f60718"
}

Change only the named fields and send the request again. Agents should do the same, rather than rewriting the whole request.

Which errors to retry

Retry?	Errors
Yes, with the same `Idempotency-Key`, after a short wait	Network errors and timeouts, `500`, `409 idempotency_in_progress`
Yes, after `Retry-After`	`429 rate_limited`
Not until the reset	`429 quota_exceeded`
Only after fixing the request	`400`, `413`, `415`, `422`
Not without a human	`401`, `403`, `404`, `409 conflict`, `421`, `503`

A failed request never uses quota, so a corrected retry costs nothing extra.

Getting help

Write to support@urnextdoor.com with the request_id, the time, the endpoint and what you expected. Never include your API key: support never needs it. You can also see recent requests and their status codes in Settings > API keys.

Next steps

Last updated October 15, 2026