Errors

When a call fails, Notabene answers with an HTTP status and a JSON body that says what to correct.

The two shapes of an error

Most errors are a problem document: a status, a short title and a detail with the reason. A request that fails validation lists each problem under errors instead, with the field when it can name one.

Problem401Validation400JSONJSON

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "unauthorized"
}

{
  "errors": [
    {
      "field": "ref",
      "error": "INVALID_VALUE",
      "message": "ref must be a UUID"
    }
  ]
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "unauthorized"
}

{
  "errors": [
    {
      "field": "ref",
      "error": "INVALID_VALUE",
      "message": "ref must be a UUID"
    }
  ]
}

In a validation error, error is one of MISSING_REQUIRED_FIELD, INVALID_VALUE or INVALID_REQUEST, and message gives the reason.

HTTP statuses

Status	What it means	What to do
400	The request is invalid: a field is missing or malformed, or the call does not apply to the transfer as it is.	Correct the request. Sending it again unchanged gives the same answer.
401	The access token is missing, malformed or expired.	Request a new token, as described in Authentication.
403	The token is valid but cannot make this call.	Use a token with the permission the message names.
404	What the call looks for does not exist, or is not yours to see.	Check the id or address.
409	The request conflicts with what already exists, such as a `ref` used for another transfer.	Read the message. Some conflicts clear if you send the request again.
429	Too many requests: more than 6,000 calls in 300 seconds. Every endpoint then refuses your calls for 10 seconds.	Wait, then send the request again, as Rate limiting shows.
500 and above	Notabene could not complete the call.	Send the request again after a pause.

Status	What it means	What to do
`400`	The request is invalid: a field is missing or malformed, or the call does not apply to the transfer as it is.	Correct the request. Sending it again unchanged gives the same answer.
`401`	The access token is missing, malformed or expired.	Request a new token, as described in Authentication.
`403`	The token is valid but cannot make this call.	Use a token with the permission the message names.
`404`	What the call looks for does not exist, or is not yours to see.	Check the id or address.
`409`	The request conflicts with what already exists, such as a `ref` used for another transfer.	Read the message. Some conflicts clear if you send the request again.
`429`	Too many requests: more than 6,000 calls in 300 seconds. Every endpoint then refuses your calls for 10 seconds.	Wait, then send the request again, as Rate limiting shows.
`500` and above	Notabene could not complete the call.	Send the request again after a pause.

Messages you may see

Answer	From	What to do
400 with `expected required property amount to be present`	POST`/api/v1/transfers`	Add the missing field. The message names it.
400 with `ref must be a UUID`	POST`/api/v1/transfers`	Send a UUID of yours as `ref`.
400 with `originator or originator_id is required`	POST`/api/v1/transfers`	Name your customer who sends the funds, or for a deposit, the sending institution or your own DID.
400 with `beneficiary_entity_did or settlement_address is required`	POST`/api/v1/transfers`	Send the destination address.
400 with `is not a valid eip155 address` or `bip122 address`	POST`/api/v1/transfers`	Send the address as CAIP-10, or as a bare address on the asset’s chain.
400 with `invalid amount`	POST`/api/v1/transfers`	Send the amount as a string in the asset’s whole units, such as `"0.5"`.
400 with `invalid beneficiary_entity_did`	POST`/api/v1/transfers`	Send the DID of the counterparty institution, or leave the field out.
400 with `field exceeds its maximum length`	POST`/api/v1/transfers`	A name part is longer than 100 characters. Shorten it.
400 with `unknown asset symbol`	POST`/api/v1/transfers`	Use an asset from Assets.
400 with `expected required property reason to be present`	POST`/api/v1/transfers/{id}/force-authorize`	Give a `reason`.
400 with `cannot force-authorize a concluded tx`	POST`/api/v1/transfers/{id}/force-authorize`	The transfer is already `Settled` or `Rejected`. There is nothing to approve.
401 with `unauthorized`	Any call	Send the token in the `Authorization` header.
401 with `invalid bearer token`	Any call	The token is malformed, expired or revoked. Request a new one.
403 with `missing required scopes`	Any call	The token lacks the permission the message names.
403 with `token subject does not match customer`	Calls under `/api/v1/customers/{customer_ref}/`	A delegate token was used for another customer.
404 with `address owner not found`	POST`/api/v1/wallet-ownerships/discover`	No institution registered the address. Ask your customer who sent the funds.
409 with `a transfer with this ref already exists with different content`	POST`/api/v1/transfers`	A transfer with this `ref` exists. Sending a create again says what it means.
409 with `transfer already settled with a different settlement id`	POST`/api/v1/transfers/{id}/settle`	The transfer already has a hash. Check which one is right.
409 on approve	POST`/api/v1/transfers/{id}/force-authorize`	The transfer changed while it was being approved. Send the request again.

Answer	From	What to do
`400` with `expected required property amount to be present`	`POST /api/v1/transfers`	Add the missing field. The message names it.
`400` with `ref must be a UUID`	`POST /api/v1/transfers`	Send a UUID of yours as `ref`.
`400` with `originator or originator_id is required`	`POST /api/v1/transfers`	Name your customer who sends the funds, or for a deposit, the sending institution or your own DID.
`400` with `beneficiary_entity_did or settlement_address is required`	`POST /api/v1/transfers`	Send the destination address.
`400` with `is not a valid eip155 address` or `bip122 address`	`POST /api/v1/transfers`	Send the address as CAIP-10, or as a bare address on the asset’s chain.
`400` with `invalid amount`	`POST /api/v1/transfers`	Send the amount as a string in the asset’s whole units, such as `"0.5"`.
`400` with `invalid beneficiary_entity_did`	`POST /api/v1/transfers`	Send the DID of the counterparty institution, or leave the field out.
`400` with `field exceeds its maximum length`	`POST /api/v1/transfers`	A name part is longer than 100 characters. Shorten it.
`400` with `unknown asset symbol`	`POST /api/v1/transfers`	Use an asset from Assets.
`400` with `expected required property reason to be present`	`POST /api/v1/transfers/{id}/force-authorize`	Give a `reason`.
`400` with `cannot force-authorize a concluded tx`	`POST /api/v1/transfers/{id}/force-authorize`	The transfer is already `Settled` or `Rejected`. There is nothing to approve.
`401` with `unauthorized`	Any call	Send the token in the `Authorization` header.
`401` with `invalid bearer token`	Any call	The token is malformed, expired or revoked. Request a new one.
`403` with `missing required scopes`	Any call	The token lacks the permission the message names.
`403` with `token subject does not match customer`	Calls under `/api/v1/customers/{customer_ref}/`	A delegate token was used for another customer.
`404` with `address owner not found`	`POST /api/v1/wallet-ownerships/discover`	No institution registered the address. Ask your customer who sent the funds.
`409` with `a transfer with this ref already exists with different content`	`POST /api/v1/transfers`	A transfer with this `ref` exists. Sending a create again says what it means.
`409` with `transfer already settled with a different settlement id`	`POST /api/v1/transfers/{id}/settle`	The transfer already has a hash. Check which one is right.
`409` on approve	`POST /api/v1/transfers/{id}/force-authorize`	The transfer changed while it was being approved. Send the request again.

Sending a request again

You can send a request again when it failed with a 5xx or a 429, or got no answer at all. Wait longer before each attempt, for example 1, 2 and then 4 seconds, as Rate limiting shows.

Sending a create again

Creating a transfer is safe to retry because Notabene never creates two transfers with the same ref. What Notabene answers depends on what you send the second time.

You send	Notabene answers	What it means
The same request, with the same `ref`	201 with the same transfer, or 409 with `a transfer with this ref already exists with different content`	Your first request created the transfer. Find it by `ref` in its `transfer.created.v3` event.
Other content, with a `ref` you used before	409 with the same message	The `ref` belongs to another transfer. Give this one a new UUID.
A new `ref`	201 with a new transfer	A second transfer. Use a new `ref` only for a new transfer.

You send	Notabene answers	What it means
The same request, with the same `ref`	`201` with the same transfer, or `409` with `a transfer with this ref already exists with different content`	Your first request created the transfer. Find it by `ref` in its `transfer.created.v3` event.
Other content, with a `ref` you used before	`409` with the same message	The `ref` belongs to another transfer. Give this one a new UUID.
A new `ref`	`201` with a new transfer	A second transfer. Use a new `ref` only for a new transfer.

Recording the same hash on a transfer again answers 200. For any other 4xx, apart from a 409 on approve and a 429, correct the request before you send it again.

When you contact support

Write to [email protected] with the transfer id, the call, the time it was made, and the status and body of the response. A request id to quote is still to be published. (placeholder)