Skip to main content

​
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
  • 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 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: 
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual\" is required. Verify your request and try again."
  }
}
Invalid phone format: 
{
  "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: 
{
  "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 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
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 Entity Errors reference.

Identity Verification Guide

Next: verify your user’s identity to unlock products.

Entity Errors Reference

Full list of error codes, types, and sub-types.