> ## Documentation Index
> Fetch the complete documentation index at: https://docs.methodfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Errors — What Can Go Wrong and How to Handle It

> What can go wrong during Entity creation and how to handle it.

## Entity Errors and Edge Cases

The most common issues during Entity creation stem from missing or incorrectly formatted user information. Understanding these helps you design an onboarding flow that minimizes friction and handles errors gracefully.

* **Missing required fields**: Entity creation requires certain identifying information (at minimum, a name and phone number for individuals). If required fields are omitted, the creation will fail. In your user experience, this typically means your onboarding form should collect all necessary fields upfront and validate completeness before submission. If you're collecting information across multiple screens, ensure the full set is available when you create the Entity.
* **Invalid formats**: PII fields must meet specific format requirements, phone numbers must be valid US numbers, dates of birth must be real dates, and so on. Customer-side validation catches most of these issues before they reach Method's API. Design your input fields with appropriate format masks, validation rules, and helpful error messages so users can correct issues immediately rather than encountering failures downstream.

### Immutable PII Fields

Once a PII field has been set to a non-null value on an Entity (name, phone, DOB, SSN), it **cannot be changed**. If a user enters incorrect information and it gets submitted to Method, you cannot correct it via the API.

**How to handle it:**

* For fields that are still `null`, you can update them at any time via the [Update endpoint](/reference/entities/update-entity)
* For genuine corrections (e.g., legal name change), contact Method support
* You may need to create a new Entity for that user

### Operations on Disabled Entities

If an Entity transitions to `disabled` (via consent withdrawal or a compliance event), any attempt to initiate new operations — connecting accounts, creating payments, requesting products — will fail. Existing data remains readable.

**How to handle it:** Check the Entity's `status` before initiating operations. If `disabled`, display a clear message and prevent actions that would fail. See [Entity Lifecycle](/guides/entities/lifecycle) for more on state transitions.

### Phone Number Formatting

Phone numbers must be in **E.164 format** (e.g., `+15121234567`). Common issues:

* Missing country code (`5121234567` instead of `+15121234567`)
* Including formatting characters (`(512) 123-4567` instead of `+15121234567`)
* Non-US numbers (Method currently supports US numbers only)

Validate and normalize phone numbers on your end before submitting to Method.

### Common Error Responses

When Entity creation or updates fail, Method returns structured error responses. Here are the most common:

**Missing required field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual\" is required. Verify your request and try again."
  }
}
```

**Invalid phone format:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual.phone\" is in an invalid format. Verify your request and try again."
  }
}
```

**Attempting to update an immutable field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "ENTITY_UPDATE_INVALID",
    "message": "Updates are only allowed on fields that have not been set. Verify your request and try again."
  }
}
```

For the complete list of Entity error codes, see [Entity Errors](/reference/errors/entity-errors) in the API Reference.

### When Issues Persist

If Entity creation consistently fails, first check the `error` field on the API response — it contains structured details about what went wrong. Most issues can be resolved by fixing input data and retrying.

If the error is unclear or you believe it's incorrect, contact Method support with:

* The Entity ID (`ent_...`) if one was created
* The full error response
* The request payload that triggered the error

<Note>
  Entity errors should be handled as a normal part of your onboarding flow,
  not as exceptional failures. Validate input early, provide clear error
  messaging, and allow users to correct and retry without starting over.
  For engineering teams: see the full error codes and response formats in the
  <a href="/reference/errors/entity-errors">Entity Errors reference</a>.
</Note>

<CardGroup cols={2}>
  <Card title="Identity Verification Guide" icon="shield-check" href="/guides/identity-verification/overview">
    Next: verify your user's identity to unlock products.
  </Card>

  <Card title="Entity Errors Reference" icon="code" href="/reference/errors/entity-errors">
    Full list of error codes, types, and sub-types.
  </Card>
</CardGroup>