Copy page

Développeurs

Errors

Every error, on every endpoint, has the same shape:

Code
{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope(s): calendar:write.",
    "details": { "required": ["calendar:write"], "missing": ["calendar:write"] },
    "request_id": "3f2b1c9e-8a4d-4b21-9f77-2c6e1a5b0d33"
  }
}

Branch on code, never on message. Codes are part of the contract; messages are written for humans and may be reworded.

request_id

Every response carries one, and it is also written to our logs. Quote it when you contact support and we can pull up the exact request — including, if the workspace has debug capture enabled, the payload we received. It saves a round of "can you reproduce it?" every time.

Status codes

Status	Meaning
400	The request was malformed or failed validation
401	Authentication failed — key missing, invalid, revoked or expired
403	Authenticated, but not allowed: scope, IP/origin, or revoked grant
404	No such resource — or it is outside the properties you were granted
409	Idempotency conflict, or a block over nights a stay already occupies
429	Rate limited
5xx	Something broke on our side. Retry with backoff

Codes

Authentication (401)

Code	Meaning
missing_credentials	No Authorization or X-Api-Key header
invalid_credentials	The credential is not recognised
key_revoked	The workspace revoked this key
key_expired	The key passed its expiry date
token_expired	The OAuth access token expired — refresh it and retry
token_revoked	The OAuth access token was revoked; do not retry

Authorisation (403)

Code	Meaning
insufficient_scope	Your effective scopes do not include what this endpoint needs
grant_revoked	The workspace withdrew your access
integration_suspended	Noé suspended your integration
integration_not_approved	Your integration is not approved for API access
app_mismatch	X-Noe-App does not match the key you authenticated with
ip_not_allowed	Your address is not on the key's allowlist
origin_not_allowed	Your browser origin is not on the key's allowlist
tenant_suspended	The workspace itself is suspended

Requests (400 / 404 / 409)

Code	Meaning
validation_failed	Payload or query parameters were rejected. See details.fields
not_found	No such resource, or outside your property scope
idempotency_key_required	A write arrived without Idempotency-Key
idempotency_key_reused	That key was already used for a different payload
idempotency_in_progress	An identical request is still being processed
stay_conflict	A block would cover nights a stay already occupies. See details.conflicts

Stay conflicts (409)

A block cannot be created over — or moved onto — nights that a reservation or a long stay already occupies, on the property itself or on a property it shares availability with. Nothing is written. details.conflicts lists what is in the way, without any guest information:

Code
{
  "error": {
    "code": "stay_conflict",
    "message": "These dates are already occupied by a stay on this property or a property it shares availability with.",
    "details": {
      "conflicts": [
        {
          "kind": "reservation",
          "property_id": "0f8b1a2c-4d5e-4f60-9a71-2b3c4d5e6f70",
          "reservation_id": "5a1d2e3f-4b5c-4d6e-8f70-1a2b3c4d5e6f",
          "check_in": "2026-11-10",
          "check_out": "2026-11-13",
          "status": "confirmed"
        }
      ]
    },
    "request_id": "…"
  }
}

kind is reservation or mid_term; check_out is the departure day. For a property outside your grant, property_id and reservation_id are null. Shrinking a block, or changing only its reason, is never refused.

Which errors to retry

Retry 429 (honouring Retry-After), 5xx, and network timeouts — timeouts are safe precisely because writes are idempotent.

Do not retry 400, 401, 403 or 404. Nothing about repeating the same request changes the outcome; surface these so a human can fix the cause.

409 idempotency_in_progress is the exception: retry it, after a short pause. Do not retry 409 stay_conflict: the nights stay occupied until that stay moves or is cancelled.

Validation details

A 400 tells you which field was wrong rather than making you guess:

Code
{
  "error": {
    "code": "validation_failed",
    "message": "The request payload failed validation.",
    "details": { "fields": ["start_date must be a calendar date in YYYY-MM-DD form"] },
    "request_id": "…"
  }
}

Batch responses

Batch endpoints return 207 Multi-Status with a per-item result, because one bad item should not discard ninety-nine good ones. Inspect every entry — the HTTP status alone does not tell you whether anything failed.

Code
{
  "results": [
    { "index": 0, "status": 201, "data": { "id": "…", "object": "block" } },
    {
      "index": 1,
      "status": 404,
      "error": { "code": "not_found", "message": "No property found with id …" }
    }
  ]
}