Common Odoo API Integration Errors (And How to Fix Them)

Introduction: The Integration "Black Box"

Odoo's External API is a powerful gateway. It allows your e-commerce store, mobile app, or legacy software to "talk" to Odoo directly using standard XML-RPC or JSON-RPC.

But when it breaks, it breaks silently. You get a generic 500 Internal Server Error or a cryptic Fault 1 code, leaving developers staring at logs for hours.

In our experience auditing over 100+ integrations, we've found that 80% of API failures stem from just 5 common errors. This guide strips away the complexity and gives you the exact code fixes to get your data flowing again.

Error #1: The "Access Denied" Authentication Loop

This is the "Hello World" of API errors. You send your credentials, but Odoo slams the door.

The Common Cause:

Most developers try to use their Account Password (the one used to log in to the UI) for the API. In Odoo 16, 17, and 18, if you have Two-Factor Authentication (2FA) or OAuth enabled, your regular password will not work.

The Fix: Generate a Dedicated API Key

# DON'T do this:
password = "my_super_secret_password"

# DO this:
password = "7891b48590c29a59547d..."  # Your Generated API Key

Error #2: The "Many2many" Write Crash

You are trying to add a Tag to a Contact or a Tax to an Invoice line. You send a list of IDs like [4, 8, 12], but Odoo crashes.

The Common Cause:

Odoo relation fields (One2many and Many2many) do not accept simple lists. They require a specific tuple syntax called "Special Commands."

The Fix: Use Odoo's 3-Element Tuple Format

Cheat Sheet for Write Commands:

# Adding a tag (ID 5) to a Contact
models.execute_kw(
    db, uid, password,
    'res.partner', 'write',
    [[contact_id], {'category_id': [(4, 5)]}]
)

Error #3: The "ProtocolError" (404 Not Found)

You copy-pasted the URL from the documentation, but your script can't connect.

The Common Cause:

This is usually a Database Name or URL mismatch.

The Fix:

Error #4: Timeouts on Large Batches

Your script works fine for 10 records. But when you try to sync 5,000 products, it hangs for 60 seconds and then crashes, saving nothing.

The Common Cause:

Odoo has a hard time limit (often 60 or 900 seconds depending on hosting) for a single request. If your script doesn't finish in time, Odoo kills the process and rolls back the transaction.

The Fix: Pagination (Batching)

Never try to read or write 5,000 records in one call. Process in batches of 100 records.

# The Safe Way: Process in batches of 100
limit = 100
offset = 0

while True:
    ids = models.execute_kw(
        db, uid, password,
        'product.template', 'search',
        [[['type', '=', 'product']]],
        {'limit': limit, 'offset': offset}
    )
    
    if not ids:
        break
    
    # Process these 100 IDs
    process_products(ids)
    offset += limit

Error #5: "ValidationError: The operation cannot be completed"

You try to update a Sales Order, but Odoo says "No."

The Common Cause:

You are violating a business rule. For example, trying to edit a Sales Order that is already in "Locked" or "Done" state. Odoo protects data integrity by blocking writes on finalized documents.

The Fix:

Error Quick Reference

Frequently Asked Questions

Conclusion: Robust Integrations Require Error Handling

A good integration isn't one that just "works"; it's one that fails gracefully. By implementing proper batching, correct Many2many syntax, and secure authentication, you can build connectors that run reliably for years.