Abandon a claim BACEN never registered

curl --request POST \
  --url https://api.example.com/api/v1/dict/claims/{claimID}/abandon \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "reason": "<string>"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/dict/claims/{claimID}/abandon"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: '<string>'})
};

fetch('https://api.example.com/api/v1/dict/claims/{claimID}/abandon', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/v1/dict/claims/{claimID}/abandon"

payload = { "reason": "<string>" }
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "claim": {
    "claimType": "OWNERSHIP",
    "claimerISPB": "12345678",
    "deadline": "2025-03-14T14:30:00Z",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "keyType": "PHONE",
    "keyValue": "+5511999999999",
    "status": "OPEN",
    "bacen": {
      "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "lastModified": "2026-06-14T12:00:00Z",
      "responseTime": "2026-06-14T12:00:00Z"
    },
    "bacenClaimId": "550e8400-e29b-41d4-a716-446655440111",
    "cancelReason": "USER_REQUESTED",
    "cancelledBy": "DONOR",
    "claimerAccountNumber": "9988776",
    "claimerAccountType": "CACC",
    "claimerBranch": "0001",
    "claimerName": "João Silva",
    "claimerOpeningDate": "2020-01-15T00:00:00Z",
    "claimerTaxId": "11122233300",
    "claimerTradeName": "Silva ME",
    "claimerType": "NATURAL_PERSON",
    "completionPeriodEnd": "2025-03-21T14:30:00Z",
    "confirmReason": "USER_REQUESTED",
    "donorISPB": "87654321",
    "lastModified": "2025-03-07T14:30:00Z",
    "requestedAt": "2025-03-07T14:30:00Z",
    "resolution": "",
    "resolutionPeriodEnd": "2025-03-14T14:30:00Z",
    "resolvedAt": ""
  },
  "warning": "<string>",
  "alreadyAbandoned": true
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Abandon a claim BACEN never registered

Ends a claim this deployment initiated that BACEN never registered. Such a claim is OPEN with no BACEN id because its createClaim gave up without an answer: every claim verb refuses it with 409, the deadline sweep cannot read it at BACEN, and the claimed key stays taken by it. The claim becomes CANCELLED with resolution NOT_REGISTERED_AT_BACEN, nothing is sent to BACEN, the key is free for a new claim, and dict.claim.cancelled is emitted in the same transaction. It is refused with 409 for a claim that carries a BACEN id (cancel it instead), for a claim that is not OPEN, and while its createClaim is still pending, being sent or waiting for a retry: only an intent that exhausted its retries leaves a claim BACEN will not register. A claim BACEN did register while its answer was lost is not abandonable either: the claimer feed adopts BACEN’s id within its next tick, so check GET /api/v1/dict/discovery-feeds for a held or blocked claimer feed before abandoning. It is refused for a caller with no identifiable principal and for a claimer this deployment does not serve, requires a reason, and writes audit rows naming who, which claim and why. Idempotent — re-sending it for an abandoned claim changes nothing and is still audited.

POST

api

dict

claims

{claimID}

abandon

Abandon a claim BACEN never registered

curl --request POST \
  --url https://api.example.com/api/v1/dict/claims/{claimID}/abandon \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "reason": "<string>"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/dict/claims/{claimID}/abandon"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: '<string>'})
};

fetch('https://api.example.com/api/v1/dict/claims/{claimID}/abandon', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/v1/dict/claims/{claimID}/abandon"

payload = { "reason": "<string>" }
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "claim": {
    "claimType": "OWNERSHIP",
    "claimerISPB": "12345678",
    "deadline": "2025-03-14T14:30:00Z",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "keyType": "PHONE",
    "keyValue": "+5511999999999",
    "status": "OPEN",
    "bacen": {
      "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "lastModified": "2026-06-14T12:00:00Z",
      "responseTime": "2026-06-14T12:00:00Z"
    },
    "bacenClaimId": "550e8400-e29b-41d4-a716-446655440111",
    "cancelReason": "USER_REQUESTED",
    "cancelledBy": "DONOR",
    "claimerAccountNumber": "9988776",
    "claimerAccountType": "CACC",
    "claimerBranch": "0001",
    "claimerName": "João Silva",
    "claimerOpeningDate": "2020-01-15T00:00:00Z",
    "claimerTaxId": "11122233300",
    "claimerTradeName": "Silva ME",
    "claimerType": "NATURAL_PERSON",
    "completionPeriodEnd": "2025-03-21T14:30:00Z",
    "confirmReason": "USER_REQUESTED",
    "donorISPB": "87654321",
    "lastModified": "2025-03-07T14:30:00Z",
    "requestedAt": "2025-03-07T14:30:00Z",
    "resolution": "",
    "resolutionPeriodEnd": "2025-03-14T14:30:00Z",
    "resolvedAt": ""
  },
  "warning": "<string>",
  "alreadyAbandoned": true
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

required

Required key used to prevent replaying the mutation.

Path Parameters

claimID

string

required

The claim's own id, as the create call answered it.

Body

application/json

reason

string

required

Why this claim is being abandoned. It is recorded in the audit trail under the caller's identity. Operator prose only — never a tax id, a Pix key, an account or a holder name.

Required string length: 8 - 384

Response

claim

object

required

The claim after the call: CANCELLED with resolution NOT_REGISTERED_AT_BACEN.

Show child attributes

warning

string

required

States plainly what the abandonment did.

alreadyAbandoned

boolean

True when the claim had already been abandoned. The call then changed nothing and emitted nothing, and it is still audited under the caller's identity — re-sending the same request is safe.