Error Handling

Memory API errors use success: false, an error string and a machine-readable code. Some codes add the fields listed below. Use the code and structured fields when deciding what to do next.

HTTP status	Code	Meaning and action
200	—	The Memory operation succeeded. A write or update can still be processing.
400	`content_too_long`	Shorten the content to the Vault owner's character limit.
400	`invalid_cursor`	Use the unchanged cursor from the same operation. Omit the cursor to start again.
400	`revision_required`	Choose a retained version when restoring a live record.
401	`unauthorized`	The key is missing, invalid or revoked, or its account is inactive.
402	`quota_exceeded`	The current usage period has no request left. Inspect `limit`.
402	`payg_unavailable`	Pay-as-you-go is not available.
403	`no_access`	The selected Vault's effective permissions lack the required grant. Check both the key and your shared-Vault membership.
404	`not_found`	The route or record is unavailable through this key. View and delete also return `not_found_ids`.
404	`vault_not_found`	The selected Vault is unavailable or your account cannot access it. Select a reachable Vault from identity.
404	`version_not_found`	Read history again; the requested version is missing or no longer retained.
405	`method_not_allowed`	Use the method in the endpoint reference. The response includes an `Allow` header.
409	`revision_conflict`	Read the current record, history or trash again and reconsider the action before submitting its current revision.
409	`version_is_current`	The selected version is already the live version; no restore is needed.
409	`no_vault_bound`	No default Vault is set for a record operation without an explicit selection. Send X-Ragionex-Vault-Id or choose a default Vault you own in the dashboard.
409	`idempotency_mismatch`	The request token was already used with different write content. Do not automatically replace the token.
410	`record_deleted`	The record accepted for this request token was deleted. Do not recreate it automatically.
410	`record_expired`	The trash retention period has ended; this record can no longer be restored.
411	`length_required`	A chunked request without `Content-Length` was refused.
413	`payload_too_large`	The request body exceeds 1,048,576 bytes.
422	`validation_error`	Correct the fields listed in `errors`. Malformed JSON also returns this status.
429	`rate_limited`	Wait for the returned retry delay before another call.
429	`export_in_progress`	Another export for this account is still streaming. Retry after the returned delay.
500	`internal_error`	The service could not finish the request. Keep the request ID for support.
503	`auth_unavailable` or `busy`	Authentication is temporarily unavailable or search is busy. Respect `Retry-After`.

Other framework HTTP errors use request_failed with the message Request failed. Keep the HTTP status when handling them.

Date error wording is specified with the date fields in the Memory reference.

Validation details

errors is an array of objects with field and message. At most 20 entries are returned. For body and parameter validation, the first message is repeated in error. A Vault-header error instead uses error: "Invalid Vault header" and an errors entry whose field is X-Ragionex-Vault-Id and whose message is Send one lowercase 32-character hexadecimal Vault ID.. Nested fields can look like ids[0]; a whole-request error uses request. Raw input is not returned.

All Memory JSON request bodies reject unknown fields. Send only the list parameters documented in the reference.

Response 401 Unauthorized

{
  "success": false,
  "error": "Invalid or missing API key",
  "code": "unauthorized"
}

Response 422 Validation Error — missing content

{
  "success": false,
  "error": "content parameter is required",
  "code": "validation_error",
  "errors": [
    {
      "field": "content",
      "message": "content parameter is required"
    }
  ]
}

Quota and retry details

A quota error's limit object contains limit, used, reset_at and paths. The paths are wait_until, upgrade_url and enable_payg. Times use RFC 3339 UTC. enable_payg reports the account's overflow setting; it does not mean pay-as-you-go is available.

Every search page counts as one request. When no request is left in the usage period, the entire page is refused. Invalid search cursors are not counted; a server-side search failure gives the request back.

Response 402 Quota Exceeded

{
  "success": false,
  "error": "Request limit reached (10000 requests every 30 days). Resets at 2024-04-13 00:00 UTC. Upgrade your plan for higher limits. See https://ragionex.com/pricing for more info.",
  "code": "quota_exceeded",
  "limit": {
    "limit": 10000,
    "used": 10000,
    "reset_at": "2024-04-13T00:00:00Z",
    "paths": {
      "wait_until": "2024-04-13T00:00:00Z",
      "upgrade_url": "https://ragionex.com/pricing",
      "enable_payg": false
    }
  }
}

A rate-limit error includes retry_after_seconds and a string limit, such as 120/minute or 3/hour. A positive delay is also returned in the Retry-After header.

Response 429 Rate Limited — illustrative delay

{
  "success": false,
  "error": "Rate limit exceeded for this endpoint",
  "code": "rate_limited",
  "retry_after_seconds": 30,
  "limit": "120/minute"
}

Response headers and service failures

A Memory API 401 includes WWW-Authenticate: ApiKey realm="ragionex", header="X-API-Key". Memory access errors with status 503 include Retry-After: 5 unless a different delay is supplied.

The service returns X-Request-ID. Memory API 5xx error bodies also contain request_id. Keep it when reporting a problem; an inbound request ID does not replace the server's ID.

Response 503 Service Unavailable

{
  "success": false,
  "error": "Search is busy. Retry in a few seconds.",
  "code": "busy",
  "request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

An export interrupted after streaming starts cannot replace the partial document with an error envelope; validate its completion marker.