Errors and retries

​

The error envelope

{
  "error": {
    "type": "validation_error",
    "message": "Record validation failed",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [{ "field": "title", "code": "required", "message": "is required" }]
  }
}

• type names the kind of error (see the table below). Branch on it and on code; message is meant for people.
• details is there when the error is about something specific: each has a machine-readable code, usually the field or parameter it is about, and a message. Some codes add more: usage and limit, current_revision, or the record_id that already has a value.
• request_id is also in the X-Request-Id header of every response, errors or not. Log it, and include it when you ask for support.

​

Statuses and types

• 400: the request is malformed, such as JSON that doesn’t parse, a sort or cursor the API doesn’t know, or a body key the operation doesn’t take (unknown_parameter, naming the key). Fix the request: retrying it unchanged fails the same way.
• 401: the API key is missing, invalid, revoked or expired.
• 402: the change would go over a hard limit of your organization’s plan, such as its number of projects, collections, records, members or webhooks, or, on Free, its storage. The detail names the limit in field, with the current usage and the limit. A file larger than the plan allows (10 MB on Free, 100 MB on paid plans) is refused when its upload starts: the field is byte_size, usage is the file’s size and limit the largest upload.
• 403: the key may see the resource but not do this, for example when it lacks a scope (the message names it; there is no detail code) or is published-only. An expand that embeds what the key can’t read is not_permitted.
• 404: the resource doesn’t exist, or the key can’t see it, such as another project’s. The two look the same on purpose.
• 409: the request conflicts with the resource’s state. A deleted resource must be restored first (deleted); a record has one draft at most (draft_exists), and a live record with a pending draft can’t be published until the draft is merged (draft_pending); a collection is being migrated (migration_in_progress). Retrying helps only once the state changes; in_progress is the exception (see below).
• 422: the values don’t pass validation. For a record, each detail’s field is the field’s key in data; unknown keys in data are unknown_field, and a value another record already has in a unique field is taken, with that record’s record_id.
• 500 is an unexpected failure in the API, and 503 means a service such as search is briefly unavailable. Retry both with backoff.

​

Retry safely with Idempotency-Key

curl -X POST "https://api.nohead.io/v1/collections/blog-posts/records" \
  -H "Authorization: Bearer $NOHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9575-0f1a3f2c1d2e" \
  -d '{"data": {"title": "Hello"}}'

• The key is 1 to 255 printable ASCII characters; a UUID is a good choice. Keys are scoped to the API key that sends them.
• The first response below 500 is stored for 24 hours, validation errors included. A retry with the same key and the same request (method, path, query string and body bytes) gets that response again, with its original ETag and Location headers and Idempotent-Replayed: true. Nothing runs a second time.
• The same key with a different request is refused: 400, detail code reused. Send the same bytes when you retry, and use a new key for a new request.
• A retry while the first request is still running gets 409, detail code in_progress. Wait and retry. A request that hasn’t finished after 5 minutes is treated as abandoned, and the key can be used again.
• A 5xx response doesn’t keep the key, so retrying runs the request again.

​

Rate limits

​

What the SDKs retry

import { Nohead, RateLimitError } from "@nohead/sdk"

const nohead = new Nohead({ maxRetries: 5 })

try {
  await nohead.records.publish(id)
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry in ${error.retryAfter} s (request ${error.requestId})`)
  } else throw error
}

from nohead import Nohead, RateLimitError

nohead = Nohead(max_retries=5)

try:
    nohead.records.publish(record_id)
except RateLimitError as error:
    print(f"Retry in {error.retry_after} s (request {error.request_id})")

nohead = Nohead::Client.new(max_retries: 5)

begin
  nohead.records.publish(id)
rescue Nohead::RateLimitError => e
  puts "Retry in #{e.retry_after} s (request #{e.request_id})"
end

​

Concurrent edits

curl -X PATCH "https://api.nohead.io/v1/records/rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T" \
  -H "Authorization: Bearer $NOHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "6"' \
  -d '{"data": {"title": "Hello again"}}'

{
  "error": {
    "type": "precondition_failed",
    "message": "Record has changed since revision 6",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [{ "code": "revision_mismatch", "message": "Current revision is 7", "current_revision": 7 }]
  }
}