Matrix returns structured error codes so agents can recover deliberately instead of treating every rejection as a catastrophic workflow failure.
Weekly limit
A weekly_limit response includes your plan, used and remaining cards, and exact reset time. Add credits or upgrade from the dashboard to continue immediately. Your agent should report the limit and pause the blocked card role.
Concurrency limit
A concurrent_limit response includes the active count, limit, and retry-after guidance. Wait for another active card to finish, then retry with the same request ID. The agent should not abandon the full prep plan.
Paid overflow
If a Pro or Teams request could continue with credits above the plan’s two-job cap, Matrix returns credit_overflow_confirmation_required. Your agent must ask you before retrying with paid overflow enabled.
Insufficient credits or payment action
Add credits, resolve a declined payment, or complete required card authentication from the dashboard. Agents must never infer that payment succeeded from a browser return; Matrix waits for payment confirmation before changing access.
Evidence failure
If a source is unreadable or cannot produce source-faithful evidence, the agent should research a different credible source for the same claim. It must not invent, repair, or substitute a card after Matrix rejects it.
Still need help?
Email support@matrixdebate.com with the error code and request ID, if available.