Understanding error handling and HTTP status codes in the Perch Core API
Perch uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Perch’s servers (these are rare, but they can happen).
HTTP status codes
Status
Code
Description
200
OK
Everything worked as expected.
201
Created
Successfully created a new resource.
401
Unauthorized
No valid API key provided.
403
Forbidden
The API key doesn’t have permissions to perform the request.
404
Not Found
The requested resource doesn’t exist or you do not have permission to access it.
409
Conflict
The request conflicts with another request (perhaps due to using the same idempotent key).
422
Unprocessable Entity
The request was unacceptable, often due to missing a required parameter.
429
Too Many Requests
Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx
Server Error
Something went wrong on Perch’s end. (These are rare.)
Error response format
The error will contain a helpful message and, in some cases (409 and 422), a fields object. The fields object will contain fields that failed some validation and an array of validation errors.
// 409 - Conflict// This error indicates that a duplicate record exists for the parent // (resourceId and resourceType polymorphic association) and the supplied email address.{ "message": "Failed to create the Lead", "fields": { "resourceId": [{ "code": "NOT_UNIQUE", "message": "Failed to pass unique index constraint", }], "resourceType": [{ "code": "NOT_UNIQUE", "message": "Failed to pass unique index constraint", }], "email": [{ "code": "NOT_UNIQUE", "message": "Failed to pass unique index constraint", }] }}
Field validation error codes
When validation fails on specific fields, you’ll receive one of these error codes:
Code
Description
INVALID
The field does not follow the intended format, e.g., an invalid email address.
INCORRECT_TYPE
The field has a value of an incorrect type, e.g., a Boolean passed to a Date field.
NOT_UNIQUE
There’s a conflict in the database on this field, e.g., a unique constraint is violated.
NOT_FOUND
No records could be found for a lookup using this field.
UNSUPPORTED
The field type is unsupported. Check the supported field types in the Changeset.
REQUIRED
The field is required but is undefined or missing.
IN_USE
The field is in use by another record.
Common error scenarios
Authentication errors
401 Unauthorized
Missing X-API-Key header
Invalid or expired API key
API key format is incorrect
403 Forbidden
API key doesn’t have permission for the requested resource
Trying to access a resource outside your firm’s scope
Client errors
404 Not Found
Resource doesn’t exist (lead, plan, etc.)
Typo in the endpoint URL
Resource exists but you don’t have permission to access it
409 Conflict
Duplicate lead with same email for your firm
Idempotency key collision
Resource state conflict
422 Unprocessable Entity
Missing required fields
Invalid field values or formats
Business logic validation failures
Rate limiting
429 Too Many Requests
Exceeded your hourly rate limit
Too many requests in a short burst
Implement exponential backoff and retry logic
For 429 errors, implement exponential backoff in your retry logic. Start with a 1-second delay and double it with each retry, up to a maximum of 60 seconds.
Best practices for error handling
Always check status codes - Don’t assume requests succeeded without checking the HTTP status
Parse error messages - The message field often contains human-readable explanations
Handle field errors - Use the fields object to show specific validation errors to users
Implement retry logic - For 429 and 5xx errors, implement smart retry mechanisms
Log errors appropriately - Log enough detail for debugging but avoid logging sensitive data
Graceful degradation - Handle API errors gracefully in your user interface
Example error handling
try { const response = await fetch('/api/firmMembers/abc123/leads', { method: 'POST', headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' }, body: JSON.stringify(leadData) }); if (!response.ok) { const errorData = await response.json(); switch (response.status) { case 401: throw new Error('Authentication failed - check your API key'); case 403: throw new Error('Permission denied - contact support'); case 409: throw new Error(`Conflict: ${errorData.message}`); case 422: // Handle field validation errors handleValidationErrors(errorData.fields); break; case 429: // Implement retry with backoff await retryWithBackoff(() => makeRequest()); break; default: throw new Error(`API error: ${errorData.message}`); } } const data = await response.json(); return data;} catch (error) { console.error('API request failed:', error); // Handle error appropriately in your application}
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Perch Developer Platform","colors":{"primary":"#327766","light":"#4A9B8E","dark":"#225544"},"logo":{"light":"https://mintcdn.com/perch/aarm0-0z3T7Cpqsa/logo/light.svg?fit=max\u0026auto=format\u0026n=aarm0-0z3T7Cpqsa\u0026q=85\u0026s=9888bee08d7235bfc8b62134afbbcd38","dark":"https://mintcdn.com/perch/aarm0-0z3T7Cpqsa/logo/dark.svg?fit=max\u0026auto=format\u0026n=aarm0-0z3T7Cpqsa\u0026q=85\u0026s=3581a78d9a09760d968114a698c5d1ab"},"favicon":"https://mintcdn.com/perch/aarm0-0z3T7Cpqsa/favicon.svg?fit=max\u0026auto=format\u0026n=aarm0-0z3T7Cpqsa\u0026q=85\u0026s=23972ee76b34e87f01ac89a6b0d2bfe4","api":{"examples":{"prefill":true}},"navbar":{"links":[{"href":"mailto:support@myperch.io","label":"Contact Support"}],"primary":{"type":"button","label":"Client Portal","href":"https://app.myperch.io"}},"footer":{"socials":{"linkedin":"https://www.linkedin.com/company/perchcanada","facebook":"https://www.facebook.com/PerchCanada"}},"styling":{"latex":false},"navigation":{"global":{},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"perch","hasAudioNarration":false,"actualSubdomain":"perch","customDomains":["docs.myperch.io"],"gitSource":{"type":"github","owner":"myperch","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6a91bd89ef81b33a53331a04","clientVersion":"0.0.4160","searchFilterCounts":[{"language":"default","tag":"Get Started","count":17},{"language":"default","tag":"Lead","count":12},{"language":"default","tag":"Realtor API","count":9},{"language":"default","tag":"Realtor API Reference","count":9},{"language":"default","tag":"Core API","count":8},{"language":"default","tag":"Partner API","count":8},{"language":"default","tag":"Partner API Reference","count":8},{"language":"default","tag":"Embeds","count":5},{"language":"default","tag":"Plan","count":4},{"language":"default","tag":"Welcome","count":3}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"getting-started/errors-and-response-codes","slug":"/getting-started/errors-and-response-codes","pageMetadata":{"title":"Errors and response codes","description":"Understanding error handling and HTTP status codes in the Perch Core API","href":"/getting-started/errors-and-response-codes"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Understanding error handling and HTTP status codes in the Perch Core API\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Perch uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`2xx`})}),` range indicate success. Codes in the `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`4xx`})}),` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`5xx`})}),` range indicate an error with Perch’s servers (these are rare, but they can happen).`]}),`\n`,_jsx(Heading,{level:`2`,id:`http-status-codes`,children:`HTTP status codes`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:`Code`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`200`})}),_jsx(_components.td,{children:`OK`}),_jsx(_components.td,{children:`Everything worked as expected.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`201`})}),_jsx(_components.td,{children:`Created`}),_jsx(_components.td,{children:`Successfully created a new resource.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`401`})}),_jsx(_components.td,{children:`Unauthorized`}),_jsx(_components.td,{children:`No valid API key provided.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`403`})}),_jsx(_components.td,{children:`Forbidden`}),_jsx(_components.td,{children:`The API key doesn’t have permissions to perform the request.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`404`})}),_jsx(_components.td,{children:`Not Found`}),_jsx(_components.td,{children:`The requested resource doesn’t exist or you do not have permission to access it.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`409`})}),_jsx(_components.td,{children:`Conflict`}),_jsx(_components.td,{children:`The request conflicts with another request (perhaps due to using the same idempotent key).`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`422`})}),_jsx(_components.td,{children:`Unprocessable Entity`}),_jsx(_components.td,{children:`The request was unacceptable, often due to missing a required parameter.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`429`})}),_jsx(_components.td,{children:`Too Many Requests`}),_jsx(_components.td,{children:`Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`5xx`})}),_jsx(_components.td,{children:`Server Error`}),_jsx(_components.td,{children:`Something went wrong on Perch’s end. (These are rare.)`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`error-response-format`,children:`Error response format`}),`\n`,_jsxs(_components.p,{children:[`The error will contain a helpful `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`message`})}),` and, in some cases (`,_jsx(_components.strong,{children:_jsx(_components.code,{children:`409`})}),` and `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`422`})}),`), a `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`fields`})}),` object. The fields object will contain fields that failed some validation and an array of validation errors.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`20`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`20`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// 409 - Conflict`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// This error indicates that a duplicate record exists for the parent `})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// (resourceId and resourceType polymorphic association) and the supplied email address.`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Failed to create the Lead\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"fields\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"resourceId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [{`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"NOT_UNIQUE\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Failed to pass unique index constraint\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }],`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"resourceType\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [{`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"NOT_UNIQUE\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Failed to pass unique index constraint\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }],`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"email\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [{`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"NOT_UNIQUE\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Failed to pass unique index constraint\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`field-validation-error-codes`,children:`Field validation error codes`}),`\n`,_jsx(_components.p,{children:`When validation fails on specific fields, you’ll receive one of these error codes:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Code`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`INVALID`})}),_jsx(_components.td,{children:`The field does not follow the intended format, e.g., an invalid email address.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`INCORRECT_TYPE`})}),_jsx(_components.td,{children:`The field has a value of an incorrect type, e.g., a Boolean passed to a Date field.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`NOT_UNIQUE`})}),_jsx(_components.td,{children:`There’s a conflict in the database on this field, e.g., a unique constraint is violated.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`NOT_FOUND`})}),_jsx(_components.td,{children:`No records could be found for a lookup using this field.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`UNSUPPORTED`})}),_jsx(_components.td,{children:`The field type is unsupported. Check the supported field types in the Changeset.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`REQUIRED`})}),_jsx(_components.td,{children:`The field is required but is undefined or missing.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`IN_USE`})}),_jsx(_components.td,{children:`The field is in use by another record.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`common-error-scenarios`,children:`Common error scenarios`}),`\n`,_jsx(Heading,{level:`3`,id:`authentication-errors`,children:`Authentication errors`}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`401 Unauthorized`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Missing `,_jsx(_components.code,{children:`X-API-Key`}),` header`]}),`\n`,_jsx(_components.li,{children:`Invalid or expired API key`}),`\n`,_jsx(_components.li,{children:`API key format is incorrect`}),`\n`]}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`403 Forbidden`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`API key doesn’t have permission for the requested resource`}),`\n`,_jsx(_components.li,{children:`Trying to access a resource outside your firm’s scope`}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`client-errors`,children:`Client errors`}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`404 Not Found`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Resource doesn’t exist (lead, plan, etc.)`}),`\n`,_jsx(_components.li,{children:`Typo in the endpoint URL`}),`\n`,_jsx(_components.li,{children:`Resource exists but you don’t have permission to access it`}),`\n`]}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`409 Conflict`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Duplicate lead with same email for your firm`}),`\n`,_jsx(_components.li,{children:`Idempotency key collision`}),`\n`,_jsx(_components.li,{children:`Resource state conflict`}),`\n`]}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`422 Unprocessable Entity`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Missing required fields`}),`\n`,_jsx(_components.li,{children:`Invalid field values or formats`}),`\n`,_jsx(_components.li,{children:`Business logic validation failures`}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`rate-limiting`,children:`Rate limiting`}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`429 Too Many Requests`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Exceeded your hourly rate limit`}),`\n`,_jsx(_components.li,{children:`Too many requests in a short burst`}),`\n`,_jsx(_components.li,{children:`Implement exponential backoff and retry logic`}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`For `,_jsx(_components.code,{children:`429`}),` errors, implement exponential backoff in your retry logic. Start with a 1-second delay and double it with each retry, up to a maximum of 60 seconds.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`best-practices-for-error-handling`,children:`Best practices for error handling`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Always check status codes`}),` - Don’t assume requests succeeded without checking the HTTP status`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Parse error messages`}),` - The `,_jsx(_components.code,{children:`message`}),` field often contains human-readable explanations`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Handle field errors`}),` - Use the `,_jsx(_components.code,{children:`fields`}),` object to show specific validation errors to users`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Implement retry logic`}),` - For `,_jsx(_components.code,{children:`429`}),` and `,_jsx(_components.code,{children:`5xx`}),` errors, implement smart retry mechanisms`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Log errors appropriately`}),` - Log enough detail for debugging but avoid logging sensitive data`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Graceful degradation`}),` - Handle API errors gracefully in your user interface`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`example-error-handling`,children:`Example error handling`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`39`,language:`javascript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`javascript`,children:_jsxs(_components.code,{language:`javascript`,numberOfLines:`39`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`try`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` response`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` fetch`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'/api/firmMembers/abc123/leads'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` method:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'POST'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` headers:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'X-API-Key'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'your-api-key'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Content-Type'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'application/json'`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` body:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` JSON`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`stringify`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`leadData`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` });`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` `})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`!`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`response`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ok`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` errorData`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` response`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`json`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`();`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` `})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` switch`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`response`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`status`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` case`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 401`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` throw`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'Authentication failed - check your API key'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` case`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 403`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` throw`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'Permission denied - contact support'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` case`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 409`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` throw`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`Conflict: \"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`errorData`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`message`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` case`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 422`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` // Handle field validation errors`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` handleValidationErrors`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`errorData`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`fields`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` break`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` case`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 429`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` // Implement retry with backoff`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` retryWithBackoff`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(() `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`=>`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` makeRequest`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`());`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` break`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` default`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` throw`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`API error: \"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`errorData`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`message`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` `})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` data`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` response`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`json`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`();`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` data`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`} `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`catch`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` console`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'API request failed:'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` // Handle error appropriately in your application`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Errors and response codes","description":"Understanding error handling and HTTP status codes in the Perch Core API","href":"/getting-started/errors-and-response-codes"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"HTTP status codes","slug":"http-status-codes","depth":2,"children":[]},{"title":"Error response format","slug":"error-response-format","depth":2,"children":[]},{"title":"Field validation error codes","slug":"field-validation-error-codes","depth":2,"children":[]},{"title":"Common error scenarios","slug":"common-error-scenarios","depth":2,"children":[{"title":"Authentication errors","slug":"authentication-errors","depth":3,"children":[]},{"title":"Client errors","slug":"client-errors","depth":3,"children":[]},{"title":"Rate limiting","slug":"rate-limiting","depth":3,"children":[]}]},{"title":"Best practices for error handling","slug":"best-practices-for-error-handling","depth":2,"children":[]},{"title":"Example error handling","slug":"example-error-handling","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"perch","siteName":"Perch Developer Platform","title":"Errors and response codes - Perch Developer Platform","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-03-30T22:53:15.044Z","originalFileLocation":"getting-started/errors-and-response-codes.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Understanding error handling and HTTP status codes in the Perch Core API\">\u003cmeta data-mint-head name=\"application-name\" content=\"Perch Developer Platform\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Errors and response codes - Perch Developer Platform\">\u003cmeta data-mint-head property=\"og:description\" content=\"Understanding error handling and HTTP status codes in the Perch Core API\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Perch Developer Platform\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.myperch.io/getting-started/errors-and-response-codes\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://perch.mintlify.site/_mintlify/api/og/v2?division=Core+API\u0026amp;title=Errors+and+response+codes\u0026amp;description=Understanding+error+handling+and+HTTP+status+codes+in+the+Perch+Core+API\u0026amp;theme=6f840f7094e37b11711b992f\u0026amp;signature=6502e6daedd18a0441be04fb636252e857e416164dec5602d2ae69668ba685ff\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Errors and response codes - Perch Developer Platform\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Understanding error handling and HTTP status codes in the Perch Core API\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://perch.mintlify.site/_mintlify/api/og/v2?division=Core+API\u0026amp;title=Errors+and+response+codes\u0026amp;description=Understanding+error+handling+and+HTTP+status+codes+in+the+Perch+Core+API\u0026amp;theme=6f840f7094e37b11711b992f\u0026amp;signature=6502e6daedd18a0441be04fb636252e857e416164dec5602d2ae69668ba685ff\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/perch/3EQlvaVh22sc_HAM/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Perch Developer Platform\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#327766\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.myperch.io/getting-started/errors-and-response-codes\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/getting-started/errors-and-response-codes.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.myperch.io/#organization\",\"name\":\"Perch Developer Platform\",\"url\":\"https://docs.myperch.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/perch/aarm0-0z3T7Cpqsa/logo/light.svg?fit=max\u0026auto=format\u0026n=aarm0-0z3T7Cpqsa\u0026q=85\u0026s=9888bee08d7235bfc8b62134afbbcd38\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.myperch.io#website\",\"name\":\"Perch Developer Platform\",\"url\":\"https://docs.myperch.io\",\"publisher\":{\"@id\":\"https://docs.myperch.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.myperch.io/getting-started/errors-and-response-codes#webpage\",\"url\":\"https://docs.myperch.io/getting-started/errors-and-response-codes\",\"name\":\"Errors and response codes\",\"description\":\"Understanding error handling and HTTP status codes in the Perch Core API\",\"dateModified\":\"2026-03-30T22:53:15.044Z\",\"isPartOf\":{\"@id\":\"https://docs.myperch.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.myperch.io/getting-started/errors-and-response-codes#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.myperch.io/getting-started/errors-and-response-codes#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Core API\",\"item\":\"https://docs.myperch.io/getting-started/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Errors and response codes\",\"item\":\"https://docs.myperch.io/getting-started/errors-and-response-codes\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.myperch.io/getting-started/errors-and-response-codes#article\",\"headline\":\"Errors and response codes\",\"name\":\"Errors and response codes\",\"description\":\"Understanding error handling and HTTP status codes in the Perch Core API\",\"url\":\"https://docs.myperch.io/getting-started/errors-and-response-codes\",\"mainEntityOfPage\":{\"@id\":\"https://docs.myperch.io/getting-started/errors-and-response-codes#webpage\"},\"dateModified\":\"2026-03-30T22:53:15.044Z\",\"publisher\":{\"@id\":\"https://docs.myperch.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.myperch.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Perch Developer Platform\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Perch Developer Platform\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/getting-started/errors-and-response-codes.md","siteName":"Perch Developer Platform","nav":{"global":{},"tabs":[{"tab":"Get Started","groups":[{"group":"Welcome","pages":[{"title":"Introduction","href":""},{"title":"Integration Options","href":"/getting-started/integration-options"},{"title":"Terms of Use","href":"/getting-started/terms-of-use"}]},{"group":"Core API","pages":[{"title":"Overview","href":"/getting-started/overview"},{"title":"Leads and Plans","href":"/core-concepts/leads-and-plans"},{"title":"Authentication","href":"/getting-started/authentication"},{"title":"Postman Setup Guide","description":"Step-by-step guide to import and configure the Perch API in Postman for instant testing","href":"/getting-started/postman-setup"},{"title":"Errors and response codes","href":"/getting-started/errors-and-response-codes"},{"title":"Rate limits","description":"Understanding rate limiting policies and best practices for the Perch Core API","href":"/getting-started/rate-limits"},{"title":"Pagination and query parameters","href":"/getting-started/pagination"},{"title":"Submitting \u0026 Tracking Leads","href":"/api-reference/submitting-and-tracking-leads"}]},{"group":"Lending API","pages":[{"title":"Overview","href":"/lending-services/overview"}]},{"group":"Embeds","pages":[{"title":"Overview","href":"/embeds/overview"},{"title":"Implementation Guide","href":"/embeds/implementation"},{"title":"Customization","href":"/embeds/customization"},{"title":"Authenticated Embeds","href":"/embeds/authenticated-embeds"},{"title":"Lead Management","href":"/embeds/lead-management"}]}]},{"tab":"Partner API","pages":[{"title":"Partner API","href":"/partner-api/workflows:-firm-member/workflowsfirm-member-realtor-find-or-create"}]},{"tab":"Realtor API","pages":[{"title":"Realtor API","href":"/realtor-api/lead/list-leads-for-firmmember"}]}]},"basePath":"","title":"Errors and response codes - Perch Developer Platform","buildId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","deploymentId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","dynamics":[],"chunks":[]}