{"openapi":"3.1.0","info":{"title":"Resolve \u2014 Agent Error Resolution API","version":"1.0.0","description":"Resolve maps API error codes to structured resolution guidance for autonomous agents. Given a service name and error code, it returns a categorized resolution with retry strategy, backoff parameters, and action steps \u2014 so agents can recover from errors without human intervention.\n\nCoverage: 52+ error patterns across 20 services including OpenAI, Anthropic, Stripe, Postgres, Redis, AWS, GitHub, Twilio, SendGrid, Docker, HuggingFace, and more.\n\nFree: 500 calls\/month. Pro: $29\/month (50k calls). Fleet: $99\/month (500k calls).","contact":{"email":"hello@8bitconcepts.com"}},"servers":[{"url":"https:\/\/resolve.arflow.io","description":"Production"}],"paths":{"\/resolve":{"post":{"operationId":"resolveError","summary":"Resolve an error code to structured guidance","description":"Returns the best matching resolution for a given service and error. Matching priority: exact (service + error_code) > pattern match on message > best generic fallback for service. Use the returned resolution to decide whether to retry, how long to wait, and what action to take.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ResolveRequest"},"examples":{"rate_limit":{"summary":"OpenAI rate limit","value":{"service":"openai","error_code":"429","agent_id":"my-agent-v1"}},"pattern_match":{"summary":"HuggingFace model loading","value":{"service":"huggingface","error_code":"503","message":"Model is currently loading","agent_id":"my-agent-v1"}},"unknown_code":{"summary":"Unknown error (returns generic fallback)","value":{"service":"anthropic","error_code":"99999","message":"unexpected internal error","agent_id":"my-agent-v1"}}}}}},"responses":{"200":{"description":"Resolution found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Resolution"},"example":{"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","service":"openai","error_code":"429","category":"rate_limit","confidence":0.97,"uses":142,"resolution":{"action":"backoff_and_retry","max_retries":5,"backoff_seconds":[1,2,4,8,16],"backoff_strategy":"exponential","notes":"Switch to lower-tier model (gpt-3.5-turbo) if retry budget exhausted. Check rate limit headers: x-ratelimit-remaining-requests and x-ratelimit-reset-requests."}}}}},"400":{"description":"Missing or invalid request body","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"No resolution found for service (unknown service)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit resets"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/services":{"get":{"operationId":"listServices","summary":"List all services with resolution data","description":"Returns all service names that have resolution data. Use this to check whether a service you depend on is covered before calling \/resolve.","responses":{"200":{"description":"Service list","content":{"application\/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"string"},"example":["anthropic","aws","cloudflare","discord","docker","gemini","github","huggingface","linear","openai","opensrs","pinecone","postgres","redis","resend","sendgrid","shopify","stripe","supabase","twilio"]},"count":{"type":"integer","example":20}}}}}}}}},"\/resolve\/feedback":{"post":{"operationId":"submitFeedback","summary":"Report whether a resolution was helpful","description":"Used to improve resolution quality over time. If a resolution did not help your agent recover, report it as unhelpful so we can improve the guidance. Requires the resolution ID from a prior \/resolve response.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["resolution_id","helpful"],"properties":{"resolution_id":{"type":"string","format":"uuid","description":"The id field from the \/resolve response"},"helpful":{"type":"boolean","description":"Whether following the resolution allowed the agent to recover"},"agent_id":{"type":"string","description":"Your agent identifier (used for analytics, not stored as PII)"}}},"example":{"resolution_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","helpful":false,"agent_id":"my-agent-v1"}}}},"responses":{"200":{"description":"Feedback recorded","content":{"application\/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid request"}}}},"\/health":{"get":{"operationId":"healthCheck","summary":"Health check","responses":{"200":{"description":"Service is healthy"}}}}},"components":{"schemas":{"ResolveRequest":{"type":"object","required":["service"],"properties":{"service":{"type":"string","description":"Service name (case-insensitive). Use \/services to list available services.","example":"openai"},"error_code":{"type":"string","description":"HTTP status code or API-specific error code string","example":"429"},"message":{"type":"string","description":"Error message text, used for pattern matching when exact error_code match fails","example":"Rate limit exceeded"},"context":{"type":"object","description":"Additional context (stored with the request, not used for matching)","additionalProperties":true},"agent_id":{"type":"string","description":"Your agent identifier. Used for usage tracking and feedback correlation.","example":"my-agent-v1"}}},"Resolution":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Resolution ID \u2014 use this when submitting feedback"},"service":{"type":"string","example":"openai"},"error_code":{"type":"string","example":"429"},"category":{"type":"string","enum":["rate_limit","auth","payment","connection","timeout","not_found","server_error","overloaded","cold_start","quota","validation","general"],"description":"Error category \u2014 use for branching logic in your agent"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Match confidence. <0.75 indicates a generic fallback \u2014 consider adding your error_code to the community database."},"uses":{"type":"integer","description":"Number of times this resolution has been used"},"resolution":{"type":"object","description":"Resolution guidance. Fields vary by category.","properties":{"action":{"type":"string","example":"backoff_and_retry"},"max_retries":{"type":"integer","description":"0 means do not retry"},"backoff_seconds":{"type":"array","items":{"type":"integer"},"description":"Retry delay schedule in seconds"},"backoff_strategy":{"type":"string","enum":["exponential","fixed","linear"]},"notes":{"type":"string","description":"Human-readable guidance for the agent"}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"hint":{"type":"string"}}}}}}