{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/en-US/apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Error Handling","description":"Documentação oficial da API da plataforma de crédito embarcado Dinie. Integre produtos de crédito diretamente na sua aplicação.","siteUrl":"https://docs.dinie.com","lang":"pt-BR","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Dinie API uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["RFC 9457 Problem Details"]}," format for all error responses. Every error has a consistent structure, a machine-readable type URI, and a human-readable description."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-format","__idx":1},"children":["Error Response Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All errors are returned with content type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://api.dinie.com.br/errors/invalid-request\",\n  \"title\": \"Invalid Request\",\n  \"status\": 400,\n  \"detail\": \"The 'cpf' field is required.\",\n  \"instance\": \"/v3/customers\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"core-fields","__idx":2},"children":["Core Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (URI)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URI that identifies the error type. Resolves to the documentation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Short summary of the problem type. Consistent across all occurrences."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status code for this occurrence."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable explanation specific to this occurrence."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instance"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (URI)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URI that identifies this specific occurrence (usually the request path)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extension-fields","__idx":3},"children":["Extension Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Machine-readable sub-type (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missing_required_field"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_cpf"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["param"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request parameter that caused the error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of individual per-field errors (for validation failures)"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tip:"]}," Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," field for programmatic error handling. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," identifies the broad category, while the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," pinpoints the specific problem."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"field-validation-errors","__idx":4},"children":["Field Validation Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a request has correct syntax but invalid field values, the response includes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array with details for each invalid field:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://api.dinie.com.br/errors/validation-failed\",\n  \"title\": \"Validation Failed\",\n  \"status\": 422,\n  \"detail\": \"One or more fields failed validation.\",\n  \"errors\": [\n    {\n      \"param\": \"email\",\n      \"detail\": \"Must be a valid email address.\",\n      \"code\": \"invalid_format\"\n    },\n    {\n      \"param\": \"cpf\",\n      \"detail\": \"CPF is already registered.\",\n      \"code\": \"already_exists\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each item in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array contains:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["param"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The field name that failed validation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable explanation of the validation failure"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Machine-readable validation error code"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-type-reference","__idx":5},"children":["Error Type Reference"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Title"},"children":["Title"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When"},"children":["When"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/invalid-request"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid-request"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed syntax, missing content type, or invalid parameters"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/authentication-failed"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authentication-failed"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication Failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid credentials or token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/forbidden"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["forbidden"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Forbidden"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Valid token but insufficient permissions"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/not-found"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not-found"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not Found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource does not exist or is not accessible for this partner"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/conflict"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conflict"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conflict"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource already exists or action conflicts with current state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/validation-failed"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation-failed"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation Failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request parsed successfully but field values are invalid"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/rate-limit-exceeded"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate-limit-exceeded"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate Limit Exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Too many requests. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/errors/internal"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unexpected server error"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All type URIs are prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.dinie.com.br"]},". Click the type to see common causes, examples, and resolution."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sdk-error-handling","__idx":6},"children":["SDK Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDKs throw typed exceptions for each error category:"]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","data-title":"Node.js","header":{"title":"Node.js","controls":{"copy":{}}},"source":"import Dinie, {\n  AuthenticationError,\n  NotFoundError,\n  ValidationError,\n  RateLimitError,\n} from \"dinie\";\n\ntry {\n  const customer = await dinie.customers.create({\n    cpf: \"invalid\",\n    name: \"Joao Silva\",\n    email: \"joao@example.com\",\n  });\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.error(\"Validation failed:\", error.message);\n    for (const fieldError of error.errors) {\n      console.error(`  ${fieldError.param}: ${fieldError.detail}`);\n    }\n  } else if (error instanceof AuthenticationError) {\n    console.error(\"Authentication failed -- check your credentials\");\n  } else if (error instanceof RateLimitError) {\n    console.error(`Rate limit reached. Retry in ${error.retryAfter}s`);\n  } else if (error instanceof NotFoundError) {\n    console.error(\"Resource not found\");\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","data-title":"Ruby","header":{"title":"Ruby","controls":{"copy":{}}},"source":"require \"dinie\"\n\nbegin\n  customer = dinie.customers.create(\n    cpf: \"invalid\",\n    name: \"Joao Silva\",\n    email: \"joao@example.com\"\n  )\nrescue Dinie::ValidationError => e\n  puts \"Validation failed: #{e.message}\"\n  e.errors.each do |field_error|\n    puts \"  #{field_error.param}: #{field_error.detail}\"\n  end\nrescue Dinie::AuthenticationError\n  puts \"Authentication failed -- check your credentials\"\nrescue Dinie::RateLimitError => e\n  puts \"Rate limit reached. Retry in #{e.retry_after}s\"\nrescue Dinie::NotFoundError\n  puts \"Resource not found\"\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"from dinie import (\n    AuthenticationError,\n    NotFoundError,\n    ValidationError,\n    RateLimitError,\n)\n\ntry:\n    customer = dinie.customers.create(\n        cpf=\"invalid\",\n        name=\"Joao Silva\",\n        email=\"joao@example.com\",\n    )\nexcept ValidationError as e:\n    print(f\"Validation failed: {e.message}\")\n    for field_error in e.errors:\n        print(f\"  {field_error.param}: {field_error.detail}\")\nexcept AuthenticationError:\n    print(\"Authentication failed -- check your credentials\")\nexcept RateLimitError as e:\n    print(f\"Rate limit reached. Retry in {e.retry_after}s\")\nexcept NotFoundError:\n    print(\"Resource not found\")\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limiting","__idx":7},"children":["Rate Limiting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All responses include rate limit headers:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"X-RateLimit-Limit: 100\nX-RateLimit-Remaining: 97\nX-RateLimit-Reset: 1709478060\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When rate limited (429), the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header indicates how many seconds to wait:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Retry-After: 30\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-strategy","__idx":8},"children":["Retry Strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Not all errors should be retried. Use this table to decide:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retry?"},"children":["Retry?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Strategy"},"children":["Strategy"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the request. The payload is malformed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Once"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Renew the access token and resend."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check permissions with your account manager."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The resource does not exist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resolve the conflict (e.g., duplicate resource)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the invalid field values."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait for the time indicated in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," and resend."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exponential-backoff","__idx":9},"children":["Exponential Backoff"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For retryable errors (429, 500), use exponential backoff with jitter:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const MAX_RETRIES = 3;\n\nasync function requestWithRetry(fn: () => Promise<any>) {\n  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {\n    try {\n      return await fn();\n    } catch (error) {\n      if (!isRetryable(error) || attempt === MAX_RETRIES) throw error;\n\n      const baseDelay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s\n      const jitter = Math.random() * 500;\n      await sleep(baseDelay + jitter);\n    }\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Info:"]}," The SDKs implement automatic retries with exponential backoff for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," responses. You can configure the maximum number of retries when initializing the client."]}]}]},"headings":[{"value":"Error Handling","id":"error-handling","depth":1},{"value":"Error Response Format","id":"error-response-format","depth":2},{"value":"Core Fields","id":"core-fields","depth":3},{"value":"Extension Fields","id":"extension-fields","depth":3},{"value":"Field Validation Errors","id":"field-validation-errors","depth":2},{"value":"Error Type Reference","id":"error-type-reference","depth":2},{"value":"SDK Error Handling","id":"sdk-error-handling","depth":2},{"value":"Rate Limiting","id":"rate-limiting","depth":2},{"value":"Retry Strategy","id":"retry-strategy","depth":2},{"value":"Exponential Backoff","id":"exponential-backoff","depth":3}],"frontmatter":{"seo":{"title":"Error Handling"}},"lastModified":"2026-03-15T13:30:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/en-us/apis/concepts/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}